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System Requirements 


Disk drive(s) 
One disk drive if and only if output is sent to the 
same physical disk from which the input was taken. 
None of the programs allows time to swap disks 
during operation on a one-drive configuration. 
Therefore, two disk drives is a more practical 
configuration. 


For more information about other Microsoft products, 
contact: 


Microsoft Corporation 
18788 Northup Way 
Bellevue, WA 98004 
(206) 828-8089 
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GENERAL INTRODUCTION 


The Microsoft(R) MS(tm)-DOS Programmer's Reference Manual is 
a technical reference manual for system programmers. This 
manual contains a description and examples of all MS-DOS 2.98 
system calls and interrupts (Chapter 1). Chapter 2, "MS-DOS 
2.8 Device Drivers" contains information on how to install 
your own device drivers on MS-DOS. Two examples of device 
driver programs (one serial and one block) are included in 
Chapter 2. Chapters 3 through 5 contain’ technical 
information about MS-DOS, including MS-DOS disk allocation 
(Chapter 3), MS-DOS control blocks and work areas (Chapter 
4), and EXE file structure and loading (Chapter 5). 


CHAPTER 1 


SYSTEM CALLS 


1.1 INTRODUCTION 


MS-DOS provides two types of system calls: interrupts = and 
function requests. This chapter describes the environments 
from which these routines can be called, how to call them, 
and the processing performed by each. 


1.2 PROGRAMMING CONSIDERATIONS 


The system calls mean you don't have to invent your own ways 
to perform these primitive functions, and make it easier to 
write machine-independent programs. 


1.2.1 Calling From Macro Assembler 


The system calls can be invoked from Macro Assembler simply 
by moving any required data into registers and issuing an 
interrupt. Some of the calls destroy registers, so you may 
have to save registers before using a system call. The 
system calls can be used in macros and procedures to make 
your programs more readable; this technique is used to show 
examples of the calls. 


1.2.2 Calling From A High-Level Language 


The system calls can be invoked from any high-level language 
whose modules can be linked with assembly-language modules. 


Calling from Microsoft Basic: Different techniques are used 
to invoke system calls from the compiler and interpreter. 
Compiled modules can be linked with assembly-language 
modules; from the interpreter, the CALL statement or USER 
function can be used to execute the appropriate 8086 object 
code. 
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Calling from Microsoft Pascal: In addition to linking with 
an assembly-language module, Microsoft Pascal includes a 
function (DOSXQQ) that can be used directly from a Pascal 
program to call a function request. 

Calling from Microsoft FORTRAN: Modules compiled with 
Microsoft FORTRAN can be linked with assembly-language 
modules. 

1.2.3 Returning Control To MS-DOS 

Control can be returned to MS-DOS in any of four ways: 


1. Call Function Request 4CH 


MOV AH,4CH 
INT 21H 


This is the preferred method. 


2. Call Interrupt 20H: 
INT 20H 
3. Jump to location @ (the beginning of the Program 
Segment Prefix): 
JMP @ 
Location @ of the Program Segment Prefix contains 
an INT 20H instruction, so this technique is simply 
one step removed from the first. 
4. Call Function Request @@H: 


MOV AH, @@H 
INT 21H 


This causes a jump to location 8, so it is simply 
one step removed from technique 2, or two steps 
removed from technique 1. 
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1.2.4 Console And Printer Input/Output Calls 


The console and printer system calls let you read from and 
write to the console device and print on the printer without 
using any machine-specific codes. You can still take 
advantage of specific capabilities (display attributes such 
as positioning the cursor or erasing the screen, printer 
attributes such as double-strike or underline, etc.) by 
using constants for these codes and reassembling once with 
the correct constant values for the attributes. 


1.2.5 Disk I/O System Calls 


Many of the system calls that perform disk input and output 
require placing values into or reading values from two 
system control’ blocks: the File Control Block (FCB) and 
directory entry. 


1.3 FILE CONTROL BLOCK (FCB) 


The Program Segment Prefix includes room for two FCBs at 
offsets 5CH and 6CH. The system call descriptions refer to 
unopened and opened FCBs. An’ unopened FCB is one that 
contains only a drive specifier and filename, which can 
contain wild card characters (* and ?). An opened FCB 
contains all fields filled by the Open File system call 
(Function @FH). Table 1.1 describes the fields of the FCB. 
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Table 1.1 Fields of File Control Block (FCB) 


Size Offset 
Name (bytes) Hex Decimal 
Drive number 1 OOH ) 
Filename 8 01-88H 1-8 
Extension 3 09-@OBH 9-11 
‘Current block 2 O@CH,@DH 12,13 
Record size 2 QEH,@FH 14,15 
File size 4 19-13H 16-19 
Date of last write 2 14H,15H 29,21 
Time of last write 2 16H,17H 22,23 
Reserved 8 18-1FH 24-31 
Current record 1 20H 32 
Relative record 4 21-24H 33-36 


4 


1.3.1 Fields Of The FCB 


Drive Number (offset 90H): Specifies the disk drive; 1 
means drive A: and 2 means drive B:. If the FCB is to be 
used to create or open a file, this field can be set to @ to 
specify the default drive; the Open File system call 
Function (@FH) sets the field to the number of the default 
drive. 


Filename (offset 91H): Eight characters, left-aligned and 
padded (if necessary) with blanks. If you specify a 
reserved device name (such as LPT1), do not put a colon at 
the end. 


Extension (offset @9H): Three characters, left-aligned and 
padded (if necessary) with blanks. This field can be all 
blanks (no extension). 


Current Block (offset @CH): Points to the block (group of 
128 records) that contains the current record. This field 
and the Current Record field (offset 20H) make up the record 
pointer. This field is set to @ by the Open File system 
call. 


SYSTEM CALLS Page 1-5 


Record Size (offset @EH): The size of a logical record, in 
bytes. Set to 128 by the Open File system call. If the 
record size is not 128 bytes, you must set this field after 
opening the file. 


File Size (offset 10H): The size of the file, in bytes. 
The first word of this 4-byte field is the low-order part of 
the size. 


Date of Last Write (offset 14H): The date the file was 
created or last updated. The year, month, and day are 
mapped into two bytes as follows: 


Offset 15H 
Y Y Y Y Y Y Y M 
Be }¥ [xy [TY ][xriy ale | 


Offset 14H 
a i eo 
54 


Time of Last Write (offset 16H): The time the file was 
created or last updated. The hour, minutes, and seconds are 
mapped into two bytes as follows: 


Offset 17H 

|} H | H|H|[ RH] H[MI[ MIM I 
15 11 190 

Offset. 16H 


Is [ MIMI S| Si] sjs{ s | 
5 4 ) 


Reserved (offset 18H): These fields are reserved for use by 
MS-DOS. 


Current Record (offset 2@H): Points to one of the 128 
records in the current block. This field and the Current 
Block field (offset @CH) make up the record pointer. This 
field is not initialized by the Open File system call. You 
must set it before doing a sequential read or write to the 
file, 


Relative Record (offset 21H): Points to the currently 
selected record, counting from the beginning of the file 
(starting with @). This field is not initialized by the 
Open File system call. You must set it before doing a 
random read or write to the file. If the record size is 
less than 64 bytes, both words of this field are used; if 
the record size is 64 bytes or more, only the first three 
bytes are used. 
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‘NOTE 


If you use the FCB at offset 
5CH of the Program Segment 
Prefix, the last byte of the 
Relative Record field is the 
first byte of the unformatted 
parameter area that starts at 
offset 80H. This is the 
default Disk Transfer Address. 


1.3.2 Extended FCB 
The Extended File Control Block is used to create or search 


for directory entries of files with special attributes. It 
adds the following 7-byte prefix to the FCB: 


Size Offset 
Name (bytes) (Decimal) 
Flag byte (255, or FFH) 1 -7 
Reserved 5 -6 
Attribute byte: 1 -1 


@2H = Hidden file 
@4H = System file 
1.3.3 Directory Entry 
A directory contains one entry for each file on the disk. 


Each entry is 32 bytes; Table 1.2 describes the fields of 
an entry. 


Table 1.2 Fields of Directory Entry 


Size Offset 
Name (bytes) Hex Decimal 
Filename 8 @0-87H 0-7 
Extension 3 @8-OAH 8-19 
Attributes 1 @BH ll 


Reserved 19 @C-15H 12-21 
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Time of last write 2 16H,17H 22,23 
Date of last read 2 18H,19H 24,25 
Reserved . 2 1AH,1BH 26,27 
File size 4 1C-1FH 28-31 
1.3.4 Fields Of The FCB). ,~%., 


Filename (offset @@H): Eight characters, left-aligned and 
padded (if necessary) with blanks. MS-DOS uses the first 
byte of this field for two special codes: 


OOH (@) End of allocated directory 
E5H (229) Free directory entry 


Extension (offset @8H): Three characters, left-aligned and 
padded (if necessary) with blanks. This field can be all 
blanks (no extension). 


Attributes (offset @BH): Attributes of the file: 


Value 
Hex Binary Dec Meaning 
G1H 8088 BOG1 1 Read-only 
G2H @8898 99190 2 Hidden 
4H 8888 G100 4 System 
87H 80998 8111 7 Changeable with CHGMOD 
G8H B8808 19090 8 vVolume-ID 
GAH G881 BOBD 18 Directory 
16H 6881 91196 22 Hard attributes for FINDENTRY 
2@H 8028 BB0B 32 Archive 


Reserved (offset @CH): Reserved for MS-DOS. 
Time of Last Write (offset 16H): The time the file was 


created or last updated. The hour, minutes, and seconds are 
mapped into two bytes as follows: 


Offset 17H 

| H| H| HH] HI H|M|[ MIM | 
15 11 10 

Offset 16H 


Mi M{|M[/]S{[S|S]S]S8 
ote fee | aly ls] ss | a 


Date of Last Write (offset 18H): The date the file was 
created or last updated. The year, month, and day are 
mapped into two bytes as follows: 
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Offset 19H 
}¥}Y]¥ [yy] YJ[y]i[vryimy] 
15 9 8 


Offset 18H 
[mM] M[M|[D]D]D{D{odD Yq 
5 4 ] 


File Size (offset 1CH): The size of the file, in bytes. 
The first word of this 4-byte field is the low-order part of 
the size. 


SYSTEM CALLS Page 1-9 


1.4 SYSTEM CALL DESCRIPTIONS 
Many system calls require that parameters be loaded into one 
or more registers before the call is issued; most calls 


return information in the registers (usually a code that 
describes the success or failure of the operation). The 


description of system calls §@H-2EH includes the following: 


A drawing of the 8988 registers that shows their 
contents before and after the system call. 


A more complete description of the register 
contents required before the system call. 


A description of the processing performed. 


A more complete description of the register 
contents after the system call. 


An example of its use. 


The description of system calls 2FH-57H includes the 
following: 


A drawing of the 8088 registers that shows their 
a contents before and after the system call. 


A more complete description of the register 
contents required before the system call. 


A description of the processing performed. 
Error returns from the system call. 
An example of its use. 


Figure 1 is an example of how each system call is described. 
Function 27H, Random Block Read, is shown. 
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Call 
AH = 27H 
DS:DX 
Opened FCB 
Cx 
Number of blocks to read 


Return 

AL 

Read completed successfully 
EOF 

End of segment 

EOF, partial record 


Cx 
Number of blocks read 


Figure l. Example of System Call Description 


1.4.1 Programming Examples 


A macro is defined for each system call, then used in some 
examples. In addition, a few other macros are defined for 
use in the examples. The use of macros allows the examples 
to be more complete programs, rather than isolated uses of 
the system calls. All macro definitions are listed at the 
end of the chapter. 


The examples are not intended to represent good programming 
practice. In particular, error checking and good human 
interface design have been sacrificed to conserve’ space. 
You may, however, find the macros a_ convenient way to 
include system calls in your assembly language programs. 


A detailed description of each system call follows. They 
are listed in numeric order; the interrupts are described 
first, then the function requests. 


NOTE 


Unless otherwise stated, all 
numbers in the system call 
descriptions -- both text and 
code -- are in hex. 
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1.5 XENIX COMPATIBLE CALLS 


MS-DOS 2.8 supports hierarchical (i.e., tree-structured) 
directories, similar to those found in the Xenix operating 
system. (For information on tree-structured directories, 
refer to the MS-DOS User's Guide.) 


The following system calls are compatible with the Xenix 
system: 


Function 39H Create Sub-Directory 


Function 3AH Remove a Directory Entry 
Function 3BH Change the Current Directory 
Function 3CH Create a File 

Function 3DH Open a File 

Function 3FH Read From File/Device 
Function 40H Write to a File or Device 
Function 41H Delete a Directory Entry 
Function 42H Move a File Pointer 

Function 43H Change Attributes 

Function 44H I/O Control for Devices 
Function 45H Duplicate a File Handle 
Function 46H Force a Duplicate of a Handle 
Function 4BH Load and Execute a Program 
Function 4CH Terminate a Process 

Function 4DH Retrieve the Return Code of a Child 


There is no restriction in MS-DOS 2.@ on the depth of a tree 
(the length of the longest path from root to leaf) except in 
the number of allocation units available. The root 
directory will have a fixed number of entries (64 for the 
single-sided disk). For non-root directories, the number of 
files per directory is only limited by the number of 
allocation units available. 


Pre-2.9 disks will appear to MS-DOS 2.8 as having only a 
root directory with files in it and no subdirectories. 


Implementation of the tree structure is simple. The root 
directory is the pre-2.@ directory. Subdirectories of the 
root have a special attribute set indicating that they are 
directories. The subdirectories themselves are files, 
linked through the FAT as usual. Their contents are 
identical in character to the contents of the root 
directory. 


Pre-2.@ programs that use system calls not described in this 
chapter will be unable to make use of files in other 
directories. Those files not necessary for the current task 
will be placed in other directories. 
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Attributes apply to the tree-structured directories in the 
following manner: 


SYSTEM CALLS 
Attribute 


volume_id 


directory 


read_only 


archive 


hidden/ 
system 


Meaning/Function 
for files 


Present at the root. 
Only one file may have 
this set. 


Meaningless. 


Old fcb-create, new 
Create, new open (for 
write or read/write) 
will fail. 


Set when file is 
written. Set/reset via 
Function 43H. 


Prevents file from 
being found in search 
first/search next. 
Old open will fail. 
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Meaning/Function 
for directories 


Meaningless. 


Indicates that the 
directory entry is a 
directory. Cannot be 
changed with 43H. 


Meaningless. 


Meaningless. 


Prevents directory 
entry from being 
found. Function 3BH 
will still work. 
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1.6 INTERRUPTS 


MS-DOS reserves interrupts 28H through 3FH for its own use. 
The table of interrupt routine addresses (vectors) is 
maintained in locations 8@H-FCH. Table 1.3 lists the 
interrupts in numeric order; Table 1.4 lists the interrupts 
in alphabetic order (of the description). User programs 
should only issue Interrupts 20H, 21H, 25H, 26H, and 27H. 
(Function Requests 4CH and 31H are the preferred method for 
Interrupts 29H and 27H for versions of MS-DOS that are 2.9 
and higher.) 


NOTE 


Interrupts 22H, 23H, and 24H 
are not interrupts that can be 
issued by user programs; they 
are simply locations where a 
segment and offset address are 
stored. 
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Table 1.3 MS-DOS Interrupts, Numeric Order 


Interrupt 

Hex Dec Description 

20H 32 Program Terminate 

21H 33 Function Request 

22H 34 Terminate Address 

23H 35 <CTRL-C> Exit Address 

24H 36 Fatal Error Abort Address 
25H 37 Absolute Disk Read 

26H 38 Absolute Disk Write 

27H 39 Terminate But Stay Resident 
28-40H 40-64 RESERVED -- DO NOT USE 


Table 1.4 MS-DOS Interrupts, Alphabetic Order 


Interrupt 

Description Hex Dec 

Absolute Disk Read 25H 37 

Absolute Disk Write 26H 38 

<CTRL-C> Exit Address 23H 35 

ms Fatal Error Abort Address 24H 36 

( Function Request 21H 33 

oe, Program Terminate 20H 32 
RESERVED -- DO NOT USE 28-40H 49-64 

Terminate Address 22H ~—-so34 


Terminate But Stay Resident 27H 39 


AND 
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Program Terminate (Interrupt 2 
aX: Call 
BX: cs 
cx 
Dx: Prefix 
Return 
None 


Program Terminate 


GH) 


Interrupt 20H causes the current process’ to 
returns control to its parent process. 


handles are closed and the di 
interrupt is almost always 
termination. 


The CS register must contain 


sk 


is used in old 


the 


cache is 


segment 


Page 1-16 


Segment address of Program Segment 


terminate and 
All open file 


cleaned. 


address 


This 


-COM files for 


of the 


Program Segment Prefix before you call this interrupt. 


The following exit addresses are restored from the 


Segment Prefix: 


Exit Address Offset 
Program Terminate @AH 
CONTROL-C QEH 
Critical Error 12H 


All file buffers are flushed to disk. 


NOTE 


Close all fil 
changed in 


changed file 
its length is 
correctly in 


a description 
File system cal 


es 


that hav 


length befor 
issuing this interrupt. If 


is 


not closed 


not recorde 
directory. 
See Functions 10H and 3EH fo 


the 


of 
ls. 


the Clos 


e 
e 
a 

’ 


d 


r 
e 


Program 
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Interrupt 20H is provided for compatibility with versions of 
MS-DOS prior to 2.0. New programs should use Function 
Request 4CH, Terminate a Process. 


Macro Definition: terminate macro 
int 20H 
endm 


Example 


7CS must be equal to PSP values given at program start 
7(ES and DS values) 

INT 2@H 
sThere is no return from this interrupt 
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Function Request (Interrupt 21H) 


Function number 
Other registers as specified in 
individual function 


As specified in individual function 


fee OO ee 
ee 
pt oReturn 
pad AOa2 = al 
es Sees, 


The AH register must contain the number of the system 
function. See Section 1.7, “Function Requests," for a 
description of the MS-DOS system functions. 


. NOTE 
No macro is defined for this 
interrupt, because all 
function descriptions in this 
chapter that define a macro 
include Interrupt 21H. 
Example 


To call the Get Time function: 


mov ah,2CH ;Get Time is Function 2CH 
int 21H 7;THIS INTERRUPT 
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Terminate Address (Interrupt 22H) 
CONTROL-C Exit Address (Interrupt 23H) 
Fatal Error Abort Address (Interrupt 24H) 


These are not true interrupts, but rather storage locations 
for a segment and offset address. The interrupts are issued 
by MS-DOS under the specified circumstance. You can change 
any of these addresses with Function Request 25H (Set 
Vector) if you prefer to write your own interrupt handlers. 


Interrupt 22H -- Terminate Address 


When a program terminates, control transfers to the address 
at offset @AH of the Program Segment Prefix. This address 
is copied into the Program Segment Prefix, from the 
Interrupt 22H vector, when the segment is created. 


Interrupt 23H -- CONTROL-C Exit Address 


If the user types CONTROL-C during keyboard input or display 
output, control transfers to the INT 23H vector in the 
interrupt table. This address is copied into the Program 
Segment Prefix, from the Interrupt 23H vector, when the 
segment is created. 


If the CONTROL-C routine preserves all registers, it can end 
with an IRET instruction (return from interrupt) to continue 
program execution. When the interrupt occurs, all registers 
are set to the value they had when the original call to 
MS-DOS was made. There are no restrictions on what a 
CONTROL-C handler can do -- including MS-DOS function calls 
-- so long as the registers are unchanged if IRET is used. 


If Function 99H or GAH (Display String or Buffered Keyboard 
Input) is interrupted by CONTROL-C, the three-byte sequence 
@3H-@DH-@AH (ETX-CR-LF) is sent to the display and the 
function resumes at the beginning of the next line. 


If the program creates a new segment and loads a second 
program that changes the CONTROL-C address, termination of 
the second program restores the CONTROL-C address to its 
value before execution of the second program. 
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Interrupt 24H -- Fatal Error Abort Address 


If a fatal disk error occurs during execution of one of the 
disk I/0 function calls, control transfers to the INT 24H 
vector in the vector table. This address is copied into the 
Program Segment Prefix, from the Interrupt 24H vector, when 
the segment is created. 


BP:SI contains the address of a Device Header Control Block 
from which additional information can be retrieved. 


NOTE 
Interrupt 24H is not issued if 


the failure occurs during 
execution of Interrupt 25H 


(Absolute Disk Read) or 
Interrupt 26H (Absolute Disk 
Write). These errors are 


usually handled by the MS-DOS 
error routine in COMMAND.COM 
that retries the disk 
operation, then gives the user 


the choice of aborting, 
, retrying the operation, or 
ignoring the error, The 


following topics give you the 
information you need about 
interpreting the error codes, 
Managing the registers and 
stack, and controlling the 
system's response to the error 
in order to write your own 
error-handling routines. 


Error Codes 


When an error-handling program gains control from Interrupt 
24H, the AX and DI registers can contain codes that describe 
the error. If Bit 7 of AH is 1, the error is either a bad 
image of the File Allocation Table or an error occurred on a 
character device. The device header passed in BP:SI can be 
examined to determine which case exists. If the attribute 
byte high order bit indicates a block device, then the error 
was a bad FAT. Otherwise, the error is on a character 
device. 
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The following are error codes for Interrupt 24H: 


Error Code 
4) 


AWPU DAKDUBWNE 


Description 

Attempt to write on write-protected 
disk 

Unknown unit 

Drive not ready 

Unknown command 

Data error 

Bad request structure length 
Seek error 

Unknown media type 

Sector not found 

Printer out of paper 

Write fault 

Read fault 

General failure 


The user stack will be in effect (the first item described 


below is at 


the 


top of the stack), and will contain the 


following from top to bottom: 


IP MS-DOS registers from 
cs issuing INT 24H 


AX User registers at time of original 
BX INT 21H request 


IP From the original INT 21H 
cs from the user to MS-DOS 


The registers are set such that if an _  IRET is executed, 
MS-DOS will respond according to (AL) as follows: 


aM 
(AL) =9 ignore the error ae Lee 
= retry the operation ~~ or Suk 
= terminate the program via INT (23 


Notes: 


1. Before giving this routine control for disk errors, 
MS-DOS performs five retries. 
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De 


For disk errors, this exit is taken only for errors 
occurring during an Interrupt 21H. It is not used 
for errors during Interrupts 25H or 26H. 


This routine is entered in a disabled state. 


The SS, SP, DS, ES, BX, CX, and DX registers must 
be preserved. 


This interrupt handler should refrain from using 
MS-DOS funtion calls. If necessary, it may use 
calls 91H through @CH. Use of any other call will 
destroy the MS-DOS stack and will leave MS-DOS in 
an unpredictable state. 


The interrupt handler must not change the contents 
of the device header. 


If the interrupt handler will handle errors’ rather 
than returning to MS-DOS, it should restore the 
application program's registers from the stack, 
remove all but the last three words on the stack, 
then issue an _  IRET. This will return to the 
program immediately after the INT 21H that 
experienced the error. Note that if this is done, 
MS-DOS will be in an unstable state until a 
function call higher than @CH is issued. 
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Absolute Disk Read (Interrupt 25H) 


Call 
AL — 
Drive number 
DS: BX 
Disk Transfer Address 
CX 
Number of sectors 
DX 
Beginning relative sector 


Error code if CF=1l 
FlagsL 
CF = @ if successful 
= 1 if not successful 


The registers must contain the following: 


AL Drive number (@=A, 1=B, etc.). 
BX Offset of Disk Transfer Address 
- (from segment address in DS). 
( cx Number of sectors to read. 
DX Beginning relative sector. 


This interrupt transfers control to the MS-DOS BIOS. The 
number of sectors specified in Cx is read from the disk to 
the Disk Transfer Address. Its requirements and processing 
are identical to Interrupt 26H, except data is read rather 
than written. 


NOTE 


All registers except the 
segment registers are 
destroyed by this call. Be 
sure to save any registers 
your program uses before 
issuing the interrupt. 


The system pushes the flags at the time of the call; they 
are still there upon return. (This is necessary because 
data is passed back in the flags.) Be sure to pop the stack 
upon return to prevent uncontrolled growth. 


‘ ‘ ’ 
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If the disk operation was successful, the Carry Flag (CF) is 
G6. If the disk operation was not successful, CF is 1 and AL 
contains the MS-DOS error code (see Interrupt 24H earlier in 
this section for the codes and their meaning). 


Macro Definition: 
abs disk read macro disk,buffer,num_sectors,start 


mov al,disk 

mov bx,offset buffer 
mov cx,num sectors 
mov dh,start 

int 25H 

endm 


Example 


The following program copies the contents of a_ single-sided 
disk in drive A: to the disk in drive B:. It uses a buffer 
of 32K bytes: 


prompt db "Source in A, target in B",13,10 
db "Any key to start. $" 
start dw M1] 
buffer db 64 dup (512 dup (?)) ;64 sectors 
int 25H: display prompt ;see Function 69H 
~* read_kbd ;see Function 68H 
Mov ex,5 ;copy 5 groups of 
364 sectors 
copy: push cx ;save the loop counter 


abs disk read 9,buffer,64,start ;THIS INTERRUPT 
abs disk write 1,buffer,64,start ;see INT 26H 


add start,64 :do the next 64 sectors 
/$° pop cx srestore the loop counter 
fr loop copy 


C. Cte 
Wole, IWF 2 retryue an Sec Let Snvareler tay bith, 
: . ; “ : Crt ey Pr TH Fcee 3, 
for A p See 2 fra jo Bed if foe a 


Aas precodt Zi ei Oot, he BO A 
neaigy . Vebeeneai, Gebos, 00 A AH 237 | 
Lar be (rn 26), be oe ae He eee BY al aul 2% 
preven Le Saree foes J Cemyeny, eee aa 
re frre ime un Ka Sea kth enuyiter Scene of arty 

t st* yyy , Ba wrt oe whip aaa | 
frrbln uth cane vith “elt tne hap Se yy 
CV thy Tp 
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Absolute Disk Write (Interrupt 26H) 


Drive number 
DS:BxX 
Disk Transfer Address 
CX 
Number of sectors 
DX 
Beginning relative sector 


RE R 


Return 
AL 
Error code if CF = l 
FLAGSL 
CF = @ if successful 
1 if not successful 


The registers must contain the following: 


AL Drive number (@=A, 1=B, etc.). 
BX offset of Disk Transfer Address 
F (from segment address in DS). 
Cx Number of sectors to write. 

DX Beginning relative sector. 


This interrupt transfers control to the MS-DOS BIOS. The 
number of sectors specified in CX is written from the Disk 
Transfer Address to the disk. Its requirements and 
processing are identical to Interrupt 25H, except data is 
written to the disk rather than read from it. 


NOTE 


All registers except the 
segment registers are 
destroyed by this call. Be 
sure to save any registers 
your program uses before 
issuing the interrupt. 


The system pushes the flags at the time of the call; they 
are still there upon return. (This is necessary because 
data is passed back in the flags.) Be sure to pop the stack 
upon return to prevent uncontrolled growth. 


SYSTEM CALLS Absolute Disk Write Page 1-26 


If the disk operation was successful, the Carry Flag (CF) is 
8. If the disk operation was not successful, CF is 1 and AL 
contains the MS-DOS error code (see Interrupt 24H for the 
codes and their meaning). 


Macro Definition: 
abs disk write macro disk,buffer,num_sectors,start 


mov al,disk 

mov bx ,offset buffer 
mov cx,num sectors 
mov dh,start 

int 26H 

endm 


Example 


The following program copies the contents of a_ single-sided 
disk in drive A: to the disk in drive B:, verifying each 
write. It uses a buffer of 32K bytes: 


off equ M] 
on equ 1 
prompt db "Source in A, target in B",13,1@ 
db "Any key to start. s" 
start dw 1] 
buffer db 64 dup (512 dup (?)) 764 sectors 
int_26H: display prompt ;see Function @9H 
read kbd ssee Function @8H 
verify on ;see Function 2EH 
Mov cx,5 rcopy 5 groups of 64 sectors 
copy: push cx ;save the loop counter 


abs disk_read @,buffer,64,start ;see INT 25H 
abs disk write 1,buffer,64,start ;THIS INTERRUPT 


add start,64 ;do the next 64 sectors 
pop cx ;restore the loop counter 
loop copy 


verify off ;see Function 2EH 
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Terminate But Stay Resident (Interrupt 27H) 


Call 

CS:DX 
First byte following 
last byte of code 


Return 
None 


The Terminate But Stay Resident call is used to make a piece 
of code remain resident in the system after its termination. 
Typically, this call is used in .COM files to allow some 
device-specific interrupt handler to remain resident to 
process asynchronous interrupts. 


DX must contain the offset (from the segment address in CS) 
of the first byte following the last byte of code in the 
program. When Interrupt 27H is executed, the program 
terminates but is treated as an extension of MS-DOS; it 


remains resident and is not overlaid by other programs when 
it terminates. 


This interrupt is provided for compatibility with versions 
of MS-DOS prior to 2.8. New programs should use Function 
31H, Keep Process. 


Macro Definition: stay resident macro last_instruc 
mov dx,offset last_instruc 


inc ax 
int 27H 
endm 


Example 


;CS must be equal to PSP values given at program start 
:(ES and DS values) 

mov DX,LastAddress 

int 27H 
;There is no return from this interrupt 
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1.7 FUNCTION REQUESTS 


Most of the MS-DOS function calls require input to be passed 
to them in registers. After setting the proper register 
values, the function may be invoked in one of the following 
ways: 


1. Place the function number in AH and execute a_ long 
call to offset 50H in your Program Segment Prefix. 
Note that programs using this method will not 
operate correctly on versions of MS-DOS that are 
lower than 2.90. 


2. Place the function number in AH and issue Interrupt 
21H. All of the examples in this chapter use this 
method. 


3. An additional method exists for programs that were 
written with different calling conventions. This 
method should be avoided for all new programs. The 
function number is placed in the CL register and 
other registers are set according to the function 


“ specification. Then, an intrasegment call is made 
to location 5 in the current code segment. That 
location contains a long call to the MS-DOS 
function dispatcher. Register AX is always 


destroyed if this method is used; otherwise, it is 
the same as normal function calls. Note that this 
method is valid only for Function Requests @@H 
through @24H. 


1.7.1 CP/M(R)-Compatible Calling Sequence 


A different sequence can be used for programs that must 
conform to CP/M calling conventions: 


1. Move any required data into the appropriate 
registers (just as in the standard sequence). 
2. Move the function number into the CL register. 
3. Execute an intrasegment call to location 5 in the 
current code segment. 
This method can only be used with functions @@H through 24H 


that do not pass a parameter in AL. Register AX is always 
destroyed when a function is called in this manner. 
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1.7.2 Treatment Of Registers 


When MS-DOS takes control after a function call, it switches 
to an internal stack. Registers not used to return 
information (except AX) are preserved. The calling 
program's stack must be large enough to accommodate the 
interrupt system -- at least 128 bytes in addition to other 
needs. 


IMPORTANT NOTE 


The macro definitions and 
extended example for MS-DOS 
system calls @@H through 2EH 
can be found at the end of 
this chapter. 


Table 1.5 lists the function requests in numeric order; 
Table 1.6 list the function requests in alphabetic order (of 
the description). é 


Table 1.5 MS-DOS Function Requests, Numeric Order 


Function 
Number Function Name 

OOH Terminate Program 
91H Read Keyboard and Echo 
92H Display Character 
83H Auxiliary Input 
O4H Auxiliary Output 
@5H Print Character 
06H Direct Console I/0 
Q7H Direct Console Input 
@8H Read Keyboard 
09H Display String 
®AH Buffered Keyboard Input 
@BH Check Keyboard Status 
OCH Flush Buffer, Read Keyboard 
@DH Disk Reset 
QEH Select Disk 
OFH Open File 
16H Close File 
11H Search for First Entry 
12H Search for Next Entry 
13H Delete File 
14H Sequential Read 
15H Sequential Write 
16H Create File 
17H Rename File 
19H Current Disk 
1AH Set Disk Transfer Address 


21H Random Read 
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22H ' Random Write 

23H File Size 

24H Set Relative Record 

25H Set Vector 

27H Random Block Read 

28H Random Block Write 

29H Parse File Name 

2AH Get Date 

2BH Set Date 

2CH Get Time 

2DH Set Time 

2EH Set/Reset Verify Flag 

2FH Get Disk Transfer Address 

3@H Get DOS Version Number 

31H Keep Process 

33H CONTROL-C Check 

35H Get Interrupt Vector 

36H Get Disk Free Space 

38H Return Country-Dependent Information 
39H Create Sub-Directory 

3AH Remove a Directory Entry 

3BH Change Current Directory 

3CH Create a File 

3DH Open a File 

3EH Close a File Handle 

3FH Read From File/Device 

40H . Write to a File/Device 

41H Delete a Directory Entry 

42H Move a File Pointer 

43H Change Attributes 

44H I/O Control for Devices 

45H Duplicate a File Handle 

46H Force a Duplicate of a Handle 
47H Return Text of Current Directory 
48H Allocate Memory 

49H Free Allocated Memory 

4AH Modify Allocated Memory Blocks 
4BH Load and Execute a Program 

4CH Terminate a Process 

4DH Retrieve the Return Code of a Child 
4EH Find Match File 

4FH Step Through a Directory Matching Files 
54H Return Current Setting of Verify 
56H Move a Directory Entry 


57H Get/Set Date/Time of File 
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Table 1.6 MS-DOS Function Requests, Alphabetic Order 


Function Name u. <4 Number 

Allocate Memory — - 48H 

Auxiliary Input 8%. = OSH 

Auxiliary Output 04H 

Buffered Keyboard Input OAH 

Change Attributes 43H 

Change the Current Directory 3BH 

Check Keyboard Status @BH 

Close a File Handle 3EH 

Close File : 10H 

CONTROL-C Check 33H 

Create a File 3CH 

Create File 16H 

Create Sub-Directory ' 39H 

Current Disk 19H 

Delete a Directory Entry ' 41H 

Delete File 13H 

Direct Console Input 07H 

Direct Console I/0 06H 

Disk Reset @DH 

Display Character Q2H 

Display String G9H 

é Duplicate a File Handle 45H 
File Size 23H 

Find Match File 4EH 

Flush Buffer, Read Keyboard OCH 

Force a Duplicate of a Handle 46H 

Free Allocated Memory 49H 

Get Date 2AH 

Get Disk Free Space 36H 

Get Disk Transfer Address 2FH 

Get DOS Version Number 30H 

Get Interrupt Vector . 35H 

Get Time 2CH 

Get/Set Date/Time of File 57H 

I/O Control for Devices 44H 

Keep Process 31H 

Load and Execute a Program 4BH 

Modify Allocated Memory Blocks 4AH 

Move a Directory Entry 56H 

Move a File Pointer 42H 

| Open a File 3DH 
Open File OFH 
| Parse File Name 29H 
Print Character @5H 

Random Block Read 27H 

| Random Block Write 28H 
: Random Read 21H 
Random Write 22H 
Read From File/Device 3FH 
Read Keyboard 08H 


Read Keyboard and Echo 01H 


SYSTEM 
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Remove a Directory Entry 

Rename File 

Retrieve the Return Code of a Child 
Return Current Setting of Verify 
Return Country-Dependent Information 
Return Text of Current Directory 
Search for First Entry 

Search for Next Entry 

Select Disk 

Sequential Read 

Sequential Write 


Set 
Set 
Set 
Set 
Set 


Date 

Disk Transfer Address 
Relative Record 

Time 

Vector 


Set/Reset Verify Flag 

Step Through a Directory Matching 
Terminate a Process 

Terminate Program 

Write to a File/Device 


3AH 
17H 
4DH 
54H 
38H 
47H 
11H 
12H 
GEH 
14H 
15H 
2BH 
1AH 
24H 
2DH 
25H 
2EH 
4FH 
4CH 
GOH 
49H 
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Terminate Program (Function @@H) 


Segment address of 
Program Segment Prefix 


ane cen 
pera 
None 
acer a 
[rinses | Fiass | 
a ae 
eae ee! 
sa 
a ae 


Function 68H is called by Interrupt 20H; it performs’ the 
same processing. 


The CS register must contain the segment address of the 
Program Segment Prefix before you call this interrupt. 


The following exit addresses are restored from the specified 
offsets in the Program Segment Prefix: 


Program terminate OAH 
CONTROL-C GEH 
Critical error 12H 


All file buffers are flushed to disk. 


Warning: Close all files that have changed in length before 
calling this function. If a changed file is not closed, its 
length is not recorded correctly in the directory. See 
Function 1@H for a description of the Close File system 
call. 


Macro Definition: terminate program macro 


XOL ah,ah 
int 21H 
endm 


Example 


;CS must be equal to PSP values given at program start 
;(ES and DS values) 

mov ah,@ 

int 21H 
;There are no returns from this interrupt 
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Read Keyboard and Echo (Function @1H) 


Call 
AH = @1H 
Return 
a es ee 
a Character typed 
ae 
a ae 
[ Fiaasn | FLAGS: 
| es 
Ls 
PS 


Function @1H waits for a character to be typed at the 
keyboard, then echos the character to the display and 
returns it in AL. If the character is CONTROL-C, Interrupt 
23H is executed. 
Macro Definition: read_kbd_and_echo macro 

mov ah, @1H 

int 21H 

endm 


Example 


The following program both displays and prints characters as 
they are typed. If RETURN is pressed, the program sends 
Line Feed-Carriage Return to both the display and _ the 
printer: 


func_@1H: read_kbd_and_echo 7;THIS FUNCTION 
print char al ;see Function @5H 
cmp al,@DH sis it a CR? 
jne func _91H sno, print it 
print char 19 ;see Function 95H 
display char 19 ssee Function 92H 


jmp func_@1H ;get another character 
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Display Character (Function 92H) 


Return 


| FLAGSH | FLAGS. 


Character to be displayed 


Function 92H displays the character in DL. If CONTROL-C is 


typed, Interrupt 23H is issued. 


Macro Definition: display char macro character 


4 


Example 


The following program converts 


mov 
mov 
int 
endm 


uppercase before displaying them: 


func 92H: read_kbd 


cmp al,"a" 
41 uppercase 
cmp al,"z" 
4i9 uppercase 
sub al,2@H 


uppercase: display char al 
jmp func _@2H: 


dl,character 
ah,@2H 
21H 


lowercase characters to 


;see Function @8H 
;don't convert 


sdon't convert 
sconvert to ASCII code 
;for uppercase 
sTHIS FUNCTION 
sget another character 
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Auxiliary Input (Function 93H) 


— Character from auxiliary device 


Function @3H waits for a character from the auxiliary input 
device, then returns the character in AL. This system call 
does not return a status or error code. 


If a CONTROL-C has been typed at console input, Interrupt 
23H is issued. 


Macro Definition: aux_input macro 
mov ah,@3H 
int 21H 
endm 


Example 
The following program prints characters as they are received 


from the auxiliary device. It stops printing when an 
end-of-file character (ASCII 26, or CONTROL-Z) is received: 


func _@3H: aux input ;THIS FUNCTION 
cmp  al1,1AH send of file? 
je continue ;yes, all done 
print char al ;see Function @5H 
jmp ~ func_@3H ;get another character 


continue: . 
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Auxiliary Output (Function @4H) 


Character for auxiliary device 


Return 


c= oe 


Function @4H sends the character in DL to the auxiliary 
output device. This system call does not return a status or 
error code. 


If a CONTROL-C has been typed at console input, Interrupt 
23H is issued. 


Macro Definition: aux_output macro character 
mov dl,character 
mov ah,@4H 
int 21H 
endm 


Example 
The following-program gets a series of strings of up to 89 


bytes from the keyboard, sending each to the auxiliary 
device. It stops when a null string (CR only) is typed: 


string db 81 dup(?) ;see Function @AH 

func _@4H:get_string 80,string ;see Function @AH 
emp string[1],9 snull string? 
je continue ;yes, all done 
mov cx, word ptr string[1] ;get string length 
mov bx,@ ;set index to @ 

send it: aux output string [bx+2] ;THIS FUNCTION 

“7 inc bx sbump index 

loop send_it ;send another character 
jmp func _@4H sget another string 


continue: . 


SYSTEM CALLS 


Print Character 


Print Character (Function @5H) 


Character for printer 


Return 
None 


Page 1-38 


Function @5H prints the character in DL on the standard 


printer device. If CONTROL-C has 


input, Interrupt 23H is issued. 


Macro Definition: print char macro character 


Example 


mov G1,character 


mov ah,@5H 
int 21H 
endm 


been typed at console 


The following program prints a walking test pattern on _ the 
printer. It stops if CONTROL-C is pressed. 


line_num db 4] 


func @5H: Mov cx ,60 ;print 6@ lines 


start line: mov b1,33 


add bl,line_num 


scharacter (!) 


;first printable ASCII 


sto offset one character 


ssave number-of-lines counter 


push cx 

mov cx ,8@ ;loop counter for line 
print_it: print char bl ;THIS FUNCTION 

inc bl 


cmp b1,126 


smove to next ASCII character 


;character (7) 


jl no reset snot there yet 


mov b1,33 


sstart over with (!) 


;last printable ASCII 
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‘ no reset: loop print_it sprint another character 

~ print_char 13 scarriage return 
print char 19 ;line feed 
inc ~line_num ;to offset lst char. of line 
pop cx srestore #-of-lines counter 


loop start_line; ;print another line 
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Direct Console 1/0 (Function @6H) 


Call 
AH = @6H 
DL 

See text 


iO] 

| PT Return 
ee eet 
pe | If DL = FFH (255) before call, 
ea Sa then Zero flag set means AL has 


character from keyboard. 
Zero flag not set means there was 


== not a character to get, and AL = @ 
aa Sea 
|S 
| eS 


The processing depends on the value in DL when the’ function 
is called: 


DL is FFH (255) -- If a character has been typed at 

. the keyboard, it is returned in AL and the Zero 
flag is @; if a character has not been typed, the 
Zero flag is l. 


DL is not FFH -- The character in DL is displayed. 


This function does not check for CONTROL-C. 


Macro Definition: dir console io macro switch 
mov dl,switch 
mov ah,@6H 
int 21H 
endm 


SYSTEM CALLS ' Direct Console 


Example 


The following program sets the system 
continuously displays the time. When 
typed, the display stops changing; when 

typed again, the clock is reset to 9 and 
again: 


time db "90:06:00.00",13,10,"S" 

; ;fo 

ten db 10 

func_@6H: set time 9,0,9,9% ssee 

read _ clock: get time ssee 
convert ch,ten,time ssee 


convert cl,ten,time[3] ;see 


convert dh,ten,time[6] ;see 


convert dl,ten,time[9] ;see 
display time ;see 
dir console io FFH ;THI 


jne_ stop zyes 

jmp read_clock ;no, 

;run 

stop: read_kbd ;see 


r jmp func_@6H ssta 
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clock to @ and 
any character is 
any character is 
the display starts 


ssee Function 89H 
r explanation of $ 


Function 2DH 
Function 2CH 
end of chapter 
end of chapter 
end of chapter 
end of chapter 
Function @9H 

S FUNCTION 

, stop timer 
keep timer 
ning 

Function @8H 
rt over 


SYSTEM CALLS Direct Console Input Page 1-42 


Direct Console Input (Function @7H) 


Character from keyboard 


Function @7H waits for a character to be typed, then returns 
it in AL. This function does not echo the character or 
check for CONTROL-C. (For a keyboard input function that 
echoes or checks for CONTROL-C, see Functions 91H or @8H.) 
Macro Definition: dir console input macro 

mov ah,@7H 

int 21H 

endm 


Example 


The following program prompts for a password (8 characters 
maximum) and places the ‘characters into a string without 
echoing them: 


password db 8 dup(?) 
prompt db "Password: s" ;see Function @9H for 
;explanation of §$ 


func @7H: display prompt ;see Function 99H 
- mov cx,8 ;maximum length of password 

xor bx,bx 780 BL can be used as index 

get_pass: dir console input ;THIS FUNCTION 
cmp al,@DH — ;was it a CR? 
je continue zyes, all done 
mov password([bx],al 7no, put character in string 
inc bx ;bump index 
loop get pass ;get another character 


continue: . ;BX has length of password+l 


SYSTEM CALLS Read Keyboard Page 1-43 


Read Keyboard (Function @8H) — 


Character from keyboard 


Function @8H waits for a character to be typed, then returns 
it in AL. If CONTROL-C is pressed, Interrupt 23H is 
executed. This function does not echo the character. (For 
a keyboard input function that echoes the character or 
checks for CONTROL-C, see Function @1H.) 


Macro Definition: read_kbd macro 
mov ah,@8H 
int 21H 
endm 


Example 


The following program prompts for a password (8 characters 
maximum) and places the characters into a string without 
echoing them: 


password db 8 dup(?) 
prompt db "Password: §" ;see Function 99H 
sfor explanation of $ 


func @8H: display prompt °- ssee Function @9H 
= mov cx,8 smaximum length of password 

xor bx,bx ;BL can be an index 

get_pass: read_kbd s;THIS FUNCTION 
cmp al,@DH ;was it a CR? 
je continue syes, all done 
mov password[bx],al ;no, put char. in string 
inc bx sbump index 
loop get_pass sget another character 


continue: . *BX has length of password+1l 
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Display String (Function 99H) 


Call 
AH = 99H 
DS:DX 
String to be displayed 


Return 
None 


DX must contain the offset (from the segment address in DS) 
of a string that ends with "S$". The string is displayed 
(the $ is not displayed). 


Macro Definition: display macro string 
mov dx,offset string 
mov ah,@9H 
int 21H 
endm 


Example 


The following program displays the hexadecimal code of the 
key that is typed: 


table db "9123456789ABCDEF" 
sixteen db 16 
result db " — §8H",13,18,"S" j;see text for 
sexplanation of § 
func @9H:read kbd and echo s;see Function @1H 
i convert al,sixteen,result[3] ;see end of chapter 
display result ;THIS FUNCTION 


jmp func_@9H sdo it again 
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Buffered Keyboard Input (Function Q@AH) 


Call 
AH = @AH 
DS:DX 
Input buffer 


Return 
None 


DX must contain the offset (from the segment address in DS) 
of an input buffer of the following form: 


Byté Contents 


i Maximum number of characters in buffer, including 
the CR (you must set this value). 


2 Actual number of characters typed, not counting 
the CR (the function sets this value). 


3-n Buffer; must be at least as long as the number 
in byte l. 


This function waits for characters to be typed. Characters 
are read from the keyboard and placed in the buffer 
beginning at the third byte until RETURN is typed. If the 
buffer fills to one less than the maximum, additional 
characters typed are ignored and ASCII 7 (BEL) is sent to 
the display until RETURN is pressed. The string can be 
edited as it is being entered. If CONTROL-C is typed, 
Interrupt 23H is issued. 


The second byte of the buffer is set to the number of 
characters entered (not counting the CR). 


Macro Definition: get string macro limit,string 


mov dx,offset string 
mov string,limit 
mov ah,@AH 

int 21H 


endm 


SYSTEM CALLS 


Example 
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The following program gets a 16-byte (maximum) string from 


the keyboard and 
it: 

buffer 

max length 

chars entered 
string 
strings per line 


crlft 


func_@AH: 


display screen: 


display line: 


fills a 24-line by 8@-character screen with 


label byte 

db 7 ;maximum length 
db ? ;number of chars. 
db 17 dup (?) 316 chars + CR 
dw ) ;how many strings 


sfit on lin 
db 13,10,"s" moe : 


get string 17,buffer ;THIS FUNCTION 

xor bx,bx 3s0 byte can be 
sused as index 

mov bl,chars entered ;get string length 

mov buffer[bx+2],"$"  ;see Function @9H 


mov al,5@H ;columns per line 

cbw 

div chars_entered ;times string fits 
;0on line 

xor ah,ah ;clear remainder 

mov strings per_line,ax ;save col. counter 

mov cx,24 7xow counter 

push cx ;save it 

mov cx,sStrings per line ;get col. counter 

display string ;see Function 99H 

loop display line 

display crlf ;see Function 99H 

pop cx ;get line counter 


loop display screen ;display 1 more line 
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( Check Keyboard Status (Function @BH) 
Ax 
ex: 
cx 
Ox: 


ma ee 

aa sae 255 (FFH) = characters in type-ahead 
; = ae buffer : 

a ae @ = no characters in type-ahead 

fo woe buffer = 


- Checks whether there are characters in the type-ahead 
buffer. If so, AL returns FFH (255); if not, AL returns Q. 
If CONTROL-C is in the buffer, Interrupt 23H is executed. 


( Macro Definition: check_kbd_status macro 
i mov ah,@BH 
int 21H 
endm 
Example 


The following program continuously displays the time until 
any key is pressed. 


time db "99:00:00.00",13,10,"S" 
ten db 198 
func _@BH: get_time ;see Function 2CH 
convert ch,ten,time ;see end of chapter 
convert cl,ten,time[3] ssee end of chapter 
convert dh,ten,time[6] ;see end of chapter 
| convert dl,ten,time([9] ssee end of chapter 
| display time ssee Function @9H 
check_kbd_status ;THIS FUNCTION 


| cmp al,FFH 1.45 
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Flush Buffer, Read Keyboard (Function @CH) 


1, 6, 7, 8, or GAH = The 
corresponding function 
is called. 

Any other value = no 
further processing. 


Return 


AL 
ae ee @ = Type-ahead buffer was 
a flushed; no other 
| eS 


processing. performed. 


The keyboard type-ahead buffer is emptied. Further 
processing depends on the value in AL when the function is 
called: 


1, 6, 7, 8, or QAH -- The corresponding MS-DOS 
function is executed. 


> 


Any other value -- No further processing; AL 
returns @. 


Macro Definition: flush and read kbd macro switch 
Sas - mov al,switch 
mov ah,@CH 
int 21H 
endm 


Example 

The following program both displays and prints characters as 
they are typed. If RETURN is pressed, the program sends 
Carriage Return-Line Feed to both the display and _ the 
printer. 


func_9CH: flush_and_read_kbd 1 ;THIS FUNCTION 


print char al ;see Function @5H 
cmp al,@DH zis it a CR? 

jne func_9CH sno, print it 
print_char 18 ;see Function @5H 
display char 16 ;see Function 92H 


jmp func_@CH ;get another character 
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Disk Reset (Function @DH) 


x Be | a | Call 
ex | eH | &_| AH = @DH 
x [ cH | a_i 
om [ ov | o | 
Cae op. . yeeeate 
Ce  |6|(CRORS 
si 
= 
a, 
[Faas | FLAGS. | 
i es 
[ps —~*d 
[_ss_SCi*d 
resSC=«d 


Function @DH is used to ensure that the internal buffer 
cache matches the disks in the drives. This function writes 
out. dirty buffers (buffers that have been modified), and 
marks all buffers in the internal cache as free. 


Function @DH flushes all file buffers. It does not update 
directory entries; you must close files that have changed 
to update their directory entries (see Function 18H, Close 
File). This function need not be called before a disk 
change if all files that changed were closed. It is 
generally used to force a known state of the system; 
CONTROL-C interrupt handlers should call this function. 


Macro Definition: disk _reset macro disk 
mov ah,@DH 


int 21H 
endm 
Example 
mov ah,@DH 
int 21H 


;There are no errors returned by this call. 


SYSTEM CALLS Select Disk 


Select Disk (Function Q@EH) 


Call 
AH = @EH 
DL 
Drive number 
(9 = A:, 1 = Bs, etc.) 


Number of logical drives 
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The drive specified in DL (@ = A:, 1 = B:, etc.) is selected 
as the default disk. The number of drives is returned in 


AL. 


Macro Definition: select disk macro disk 
‘ ~ mov dl ,disk[-64] 
mov ah,@EH 
int 21H 
endm 


Example 


The following program selects the drive not 
selected in a 2~drive system: 


func _QEH: current disk ;see Function 19H 
cmp al ,@@H sdrive A: selected? 
je select b ;yes, select B 
select _disk "A" ;THIS FUNCTION 
jmp continue 

select_b: select disk "B" ;THIS FUNCTION 


continue: . 


currently 


@ 
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Open File (Function @FH) 


Fe] a] call 
Pex [-e | AH = OFH 

ox [~cH [a] DS:DXx 
rox] «| Unopened FCB 


aa ae 

ict: = abe i Return 

ee eee ee 

| ae eee @ = Directory entry found 

a 255 (FFH) = No directory entry found 


“Dx must contain the offset (from the segment address in DS) 


of an unopened File Control Block (FCB). The disk directory 
is searched for the named file. 


If a'directory entry for the file is found, AL returns @ and 
the FCB is filled as follows: 


If the drive code was @ (default disk), it is 
changed to the actual disk used (1 = A:, 2 = Bs, 
etc.). This lets you change the default disk 
without interfering with subsequent operations on 
this file. 


The Current Block field (offset GCH) is set to 
zero. 


The Record Size (offset @EH) is set to the system 
default of 128. 


The File Size (offset 10H), Date of Last Write 
(offset 14H), and Time of Last Write (offset 16H) 
are set from the directory entry. 


Before performing a sequential disk operation on the file, 
you must set the Current Record field (offset 29H). Before 
performing a random disk operation on the file, you must set 
the Relative Record field (offset 21H). If the default 
record size (128 bytes) is not correct, set it to the 
correct length. 
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If a directory entry for the file is not found, AL returns 
FFH (255). 


Macro Definition: open macro fcb 
mov dx,offset fcb 
mov ah,@FH 
int 21H 
endm 


Example 


The following program prints the file named TEXTFILE.ASC 
that is on the disk in drive B:. If a partial record is in 
the buffer at end-of-file, the routine that prints the 
partial record prints characters until it encounters an 
end-of-file mark (ASCII 26, or CONTROL-Z) : 


fcb db 2,"TEXTEFILEASC" 


db 25 dup (?) 
buffer db 128 dup (?) 
func _OFH: set _dta buffer ;see Function 1AH 
open fcb ;THIS FUNCTION 
read_line: read_seq_ fcb ;see Function 14H 
cmp al,@2H send of file? 
. je all_done syes, go home 
cmp al,@@H ;more to come? 
j9 check_more sno, check for partial 
;record 
mov cx,128 ;yes, print the buffer 
XOX si,si ;set index to @ 
print it: print char buffer[si] ;see Function @5H 
~ inc si sbump index 
loop print_it sprint next character 
jmp ‘read line ;read another record 
check more: cmp al,@3H ;part. record to print? 
~ jne all_done ;no 
mov cx,128 syes, print it 
XOX si,si ;set index to @ 
find_eof: cmp buffer[si] ,26 send-of-file mark? 
je all_done yes 
print char buffer[{si] ;see Function @5H 
inc si ;bump index to next 
;character 


loop find eof 
all_done: close fcb ;see Function 19H 
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Close File (Function 1@H) 


Call 
AH = 10H 
DS:DX 

Opened FCB 


RRER 


Return 
AL 
@ = Directory entry found 
FFH (255) = No directory entry found 


DX must contain the offset (to the segment address in DS) of 
an opened FCB. The disk directory is searched for the file 
named in the FCB. This function must be called after a file 
is changed to update the directory entry. 


If a directory entry for the file is found, the location of 
the file is compared with the corresponding entries in the 
FCB. The directory entry is updated, if necessary, to match 
the FCB, and AL returns @Q. 


If a directory entry for the file is not found, AL returns 
FFH (255). 


Macro Definition: close macro fcb 
mov dx,offset fcb 
mov ah,1@H 
int 21H 
endm 


Example 
The following program checks the first byte of the file 


named MOD1.BAS in drive B: to see if it is FFH, and prints 
a message if it is: 


message db "Not saved in ASCII format",13,19,"S" 
fcb db 2,"MOD1 BAS" 
db 25 dup (?) 
buffer db 128 dup (?) 
func_1@H: set_dta buffer :see Function 1AH 
open fcb ;see Function @FH 


read _ seq fcb s;see Function 14H 


SYSTEM CALLS Close File 
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cmp buffer,FFH zis first byte FFH? 
jne all_done z;no 
display message ;see Function 69H 


all_ done: close fcb ;THIS FUNCTION 
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Search for First Entry (Function 11H) 


Call 
AH = 11H 
DS:DX 
Unopened FCB 


ZRER 


Return 
®@ = Directory entry found 
FFH (255) = No directory entry found 


DX must contain the offset (from the segment address in DS) 
of an unopened FCB. The disk directory is searched for the 
first matching name. The name can have the ? wild card 
character to match any character. To search for hidden or 
system files, DX must point to the first byte of the 
extended FCB prefix. 


If a directory entry for the filename in the FCB is found, 
AL returns @ and an unopened FCB of the same type (normal or 
extended) is created at the Disk Transfer Address. 


If a directory entry for the filename in the FCB is not 
found, AL returns FFH (255). 


Notes: 


If an extended FCB is used, the following search pattern is 
used: 


1. If the FCB attribute is zero, only normal file 
entries are found. Entries for volume label, 
sub-directories, hidden, and system files will not 
be returned. 


2. If the attribute field is set for hidden or system 
files, or directory entries, it is to be considered 
as an inclusive search. All normal file entries 
plus all entries matching the specified attributes 
are returned. To look at all directory = entries 
except the volume label, the attribute byte may be 
set to hidden + system + directory (all 3 bits on). 
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3. If the attribute field is set for the volume label, 
it is considered an exclusive search, and only the 
volume label entry is returned. 


Macro Definition: search first macro fcb 
mov dx,offset fcb 
mov ah,11H 
int 21H 
endm 


Example 


The following program verifies the existence of a file named 
REPORT.ASM on the disk in drive B:: 


yes db "FILE EXISTS.$" 

no db “FILE DOES NOT EXIST.S" 

fcb db 2,"REPORT ASM" 
db 25 dup (?) 

buffer db 128 dup (?) 

func_11lH: set_dta buffer ;see Function 1AH 
search first fcb ;THIS FUNCTION 

‘ cmp al,FFH ;directory entry found? 

je not_there 7;no 
display yes ;see Function 99H 
jmp continue 

not there: display no ;see Function @9H 


continue: display crlf ;see Function 69H 
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Search for Next Entry (Function 12H) 


x Ea] =~) call 
x [oe | om | AH = 12H 
ox [Ten [a | DS:Dx 
ox an 7 oe) Unopened FCB 
eee BP 
FP} sReturn 
a eee ey 
a ae Q = Directory entry found 
=a FFH (255) = No directory entry found 
PS 
8 
PSS 
a ae 


DX must contain the offset (from the segment address in DS) 
of an FCB. previously specified in a call to Function 11H. 
Function 12H is used after Function 11H (Search for First 
Entry) to find additional directory entries that match a 
filename that contains wild card characters. The disk 
directory is searched for the next matching name. The name 
can have the ? wild card character to match any character. 
To search for hidden or system files, DX must point to the 
first byte of the extended FCB prefix. 


If a directory entry for the filename in the FCB is found, 
AL returns @ and an unopened FCB of the same type (normal or 
extended) is created at the Disk Transfer Address. 


If a directory entry for the filename in the FCB is not 
found, AL returns FFH (255). 


Macro Definition: search_next macro fcb 
mov dx,offset fcb 
mov ah,12H 
int 21H 
endm 


Example 


The following program displays the number of files on the 
disk in drive B: 


message db "No files",190,13,"5" 
files db 4) 
ten db 1d 
fcb db 2222222727222" 
db 25 dup (?) 


buffer db 128 dup (?) 


SYSTEM CALLS 


func_12H: 


search dir: 


done: 
all_ done: 
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set_dta buffer ;see Function 1AH.- 

search first fcb ;see Function 11H 

cmp al,FFH ;directory entry found? 

je all done sno, no files on disk 

inc files syes, increment file 
s;counter 

search next fcb ;THIS FUNCTION 

cmp al,FFH ;directory entry found? 

je done 7no 

inc files syes, increment file 
;counter 

jmp search dir ;check again 


- convert files,ten,message ;see end of chapter 


display message ;see Function @9H 
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Delete File (Function 13H) 


Call 
AH = 13H 
DS:DX 
Unopened FCB 


Return 
9 = Directory entry found 
FFH (255) = No directory entry found 


DX must contain the offset (from the segment address in DS) 
of an unopened FCB. The directory is searched for a 
matching filename. The filename in the FCB can contain the 
? wild card character to match any character. 


If a matching directory entry is found, it is deleted from 
the directory. If the ? wild card character is used in the 
filename, all matching directory entries are deleted. AL 
returns @. 


If no matching directory entry is found, AL returns FFH 
(255). 


Macro Definition: delete macro fcb 


mov dx,offset fcb 
mov ah,13H 

int 21H 

endm 


Example 


The following program deletes each file on the disk in drive 
B: that was last written before December 31, 1982: 


year dw 1982 

month db 12 

day db 31 

files db 1] 

ten db 19 

message db "NO FILES DELETED.",13,10,"$" 


s;see Function @9H for 


sexplanation of § 
fcb db 2, "22222222722" 


ir Se Se Se Se Se Se eS 


db 25 dup (?) 


SYSTEM CALLS 


buffer 


func_13H: 


compare: 


next: 


all_done: 


4 


Delete File 


db 128 dup (?) 


set dta buffer 
search first fcb 
cmp al,FFH 

je all done 
convert date buffer 


cmp cx,year 
jg next 

cmp dl1,month 
jig next 

cmp dh,day 
jge next 
delete buffer 


inc files 


search next fcb 


cmp al,@@QH 
je compare 
cmp files,@ 


je all_done 
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s;see Function 1AH 

;see Function 11H 
;directory entry found? 
sno, no files on disk 
s;see end of chapter 
;next several lines 
;check date in directory 
sentry against date 
sgabove & check next file 
;if date in directory 
sentry isn't earlier. 
;THIS FUNCTION 

;bump deleted-files 
;counter 

;see Function 12H 
;directory entry found? 
;yes, check date 

;any files deleted? 

sno, display NO FILES 
;message. 


convert files,ten,message ;see end of chapter 


display message 


;see Function @9H 
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Sequential Read (Function 14H) 


Call 
AH = 14H 
DS:DX 

Opened FCB 


Return 

AL 

Read completed successfully 
EOF 

DTA too small 

EOF, partial record 


WNH& 


DX must contain the offset (from the segment address in DS) 
of an opened FCB. The record pointed to by the current 
block (offset @CH) and Current Record (offset 20H) fields is 
loaded at the Disk Transfer Address, then the Current Block 
and Current Record fields are incremented. 


The record size is set to the value at offset @EH in the 
FCB. 


AL returns a code that describes the processing: 


Code Meaning 
4) Read completed successfully. 
1 End-of-file, no data in the record. 
2 Not enough room at the Disk Transfer Address 


to read one record; read canceled. 


3 End-of-file; a partial record was read and 
; padded to the record length with zeros. 


Macro Definition: read_seq macro fcb 
mov dx,offset fcb 
mov ah,14H 
int 21H 
endm 
Example 


The following program displays the file named TEXTFILE.ASC 
that is on the disk in drive B:; its function is similar to 
the MS-DOS TYPE command. If a partial record is in the 
buffer at end of file, the routine that displays the partial 
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record displays characters until it encounters an 
end-of-~file mark (ASCII 26, or CONTROL-2Z) : 


fcb db 2,"TEXTFILEASC" 


db 25 dup (?) 

buffer db 128 dup (?),"s" 

func_14H: set _dta buffer ssee Function 1AH 
open fcb ;see Function @FH 

read line: read_seq fc ;THIS FUNCTION 
cmp al,@2H send-of-file? 
je all _ done ;yes 
cmp al,@2H send-of-file with partial 

srecord? 

jg check more ;yes 
display buffer ssee Function @9H 
jmp read line sget another record 

check more: cmp al,@3H spartial record in buffer? 

~ jne all done :no, go home 

XOX si,si sset index to @ 

find eof: cmp buffer[si],26 ;is character EOF? 

= je all_done _ pyes, no more to display 
display char buffer[{si] ;see Function 62H 
inc si sbump index to next 
“ ;character 

jmp find_eof ;check next character 


all_ done: close fcb ;see Function 16H 
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Sequential Write (Function 15H) 


Call 
AH = 15H 
DS:DX 
Opened FCB 
Return 
AL 
Q@@H = Write completed successfully 
O1H = Disk full 
@2H = DTA too small 


DX must contain the offset (from the segment address in DS) 
of an opened FCB. The record pointed to by Current Block 
(offset OCH) and Current Record (offset 20H) fields is 
written from the Disk Transfer Address, then the current 
block and current record fields are incremented. 


The record size is set to the value at offset Q@EH in the 
FCB. If the Record Size is less than a sector, the data at 
the Disk Transfer Address is written to a buffer; the 
buffer is written to disk when it contains a full sector of 
data, or the file is closed, or a Reset Disk system call 
(Function @DH) is issued. 


AL returns a code that describes the processing: 


Code Meaning 
g Transfer completed successfully. 
1 Disk full; write canceled. 
2 Not enough room at the Disk Transfer Address 


to write one record; write canceled 


Macro Definition: write seq macro fcb 
mov dx,offset fcb 
mov ah,15H 
int 21H 
endm 
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Example 


The following program creates a file named DIR.TMP on the 
disk in drive B: that contains the disk number (@ = A:, 1 = 
B:, etc.) and filename from each directory entry on _ the 
disk: 


record size equ 14 soffset of Record Size 
s;field in FCB 


fcbl db 2,"DIR TMP" 
db 25 dup (?) 
fcb2 db 2,°222227222222" 
db 25 dup (?) 
buffer db 128 dup (?) 
func_15H: set dta buffer ;see Function 1AH 
search first fcb2 ssee Function 11H 
cmp | al,FFH ;directory entry found? 
je all done sno, no files on disk 
create fcbl ;see Function 16H 
mov fcbl[record_ size] ,12 
sset record size to 12 
write it: write seq fcbl ;THIS FUNCTION 
search next fcb2 ;see Function 12H 
cmp al,FFH ;directory entry found? 
je all_done ;no, go home 
jmp write it syes, write the record 


all _ done: close fcbl ;see Function 16H 
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Create File (Function 16H) 


Call 
AH = 16H 
DS:DX 
Unopened FCB 


Q@@H = Empty directory found 
FFH (255) = No empty directory 
available 


DX must contain the offset (from the segment address in DS) 
of an unopened FCB. The directory is searched for an empty 
entry or an existing entry for the specified filename. 


If an empty directory entry is found, it is initialized to a 
zero-length file, the Open File system call (Function @FH) 
is called, and AL returns 8. You can create a_ hidden file 
by using an extended FCB with the attribute byte (offset 
FCB-1) set to 2. 


If an entry is found for the specified filename, all data in 
the file is released, making a zero-length file, and the 
Open File system call (Function QFH) is issued for the 
filename (in other words, if you try to create a file that 
already exists, the existing file is erased, and a new, 
empty file is created). 


If an empty directory entry is not found and there is no 
entry for the specified filename, AL returns FFH (255). 


Macro Definition: create macro fcb 
mov dx,offset fcb 
mov ah,16H 
int 21H 
endm 


Example 


The following program creates a file named DIR.TMP on the 
disk in drive B: that contains the disk number (@ = A: 
B:, etc.) and filename from each directory entry on the 
disk: 


* 
[= 
il 


SYSTEM CALLS 


record size 


fcbl 


Ecb2 


buffer 


func_16H: 


write it: 


all_done: 


A 
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equ 14 ;offset of Record Size 
;field of FCB 


db 2,"DIR TMP" 
db 25 dup (?) 
db Ze 22222272222” 


db 25 dup (?) 
db 128 dup (?) 


set dta buffer s;see Function 1AH 
search first fcb2 ;see Function 11H 
emp al,FFH sdirectory entry found? 
je all_done ;no, no files on disk 
create fcbl ;THIS FUNCTION 
mov fcbl{record size],12 

Jset record size to 12 
write seq fcbl ;see Function 15H 
search next fcb2 ssee Function 12H 
cmp ~ al,FFH ;directory entry found? 
je all done ;no, go home 
jmp write it ;yes, write the record 


close fcbl ;see Function 16H 


SYSTEM CALLS 


Rename File (Function 17H) 


Call 
AH = 17H 
DS:3DX 
Modified FCB 


Return 

AL 
@@H = Directory entry found 
FFH (255) = No directory entry 
found or destination already 
exists 


DX must contain the offset (from the segment address in DS) 
of an FCB with the drive number and filename filled in, 
followed by a second filename at offset 11H. The disk 
directory is searched for an entry that matches the first 
filename, which can contain the ? wild card character. 

If a matching directory entry is found, the filename in the 
directory entry is changed to match the second filename in 
the modified FCB (the two filenames cannot be the same 
name). If the ? wild card character is used in the second 
filename, the corresponding characters in the filename of 
the directory entry are not changed. AL returns @. 


If a matching directory entry is not found or an entry is 
found for the second filename, AL returns FFH (255). 


Macro Definition: rename macro fcb,newname 
mov dx,offset fcb 
mov ah,17H 
int 21H 
endm 


Example 


The following program prompts for the name of a file and a 
new name, then renames the file: 


fcb db 37 dup (?) 
promptl db "Filename: Ss" 
prompt2 db "New name: Ss" 
reply db 17 dup(?) 


erlf db 13,10,"$" 
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func_17H: display promptl ;see Function 99H 
get string 15,reply ;see Function @AH 
display crlf ;see Function 99H 
parse reply[(2],fcb ;see Function 29H 
display prompt2 ;see Function @9H 
get_string 15,reply ;see Function @AH 
display crlf ;see Function 99H 


parse reply[2],fcb[16]} 
ssee Function 29H 
rename fcb 7THIS FUNCTION 


‘ Bs 
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Current Disk (Function 19H) 


a ee Call 
x {oe | es AH = 19H 
os ee 
ox [ow | oo _| 
ee ee ee ae 
AL 
a eee Currently selected drive 
ae ee 
Ps 
Ps 
PF SS 
== 
AL returns the currently selected drive (@ = A:, 1 = B:, 
etc.). 


Macro Definition: current disk macro 
= mov ah,19H 
int 21H 
endm 


‘Example 


The following program displays the currently selected 
(default) drive in a 2-drive system: 


message db "Current disk is $" ;see Function @9H 
: x - sfor explanation of § 

erl 13,190, 

func_19H: display message ;see Function @9H 
current disk ;THIS FUNCTION 
cmp al,@@H sis it disk A? 
jne disk _b sno, it's disk B: 
display char "A" ;see Function 92H 
jmp all_ done 

disk b: display char “B" ;see Function 92H 


all_done: display crlf ;see Function 99H 
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Set Disk Transfer Address (Function 1AH) 


AX: 
BX: 
Cx: 
Ox: 


DS:DX 
Disk Transfer Address 


Return 
None 


DX must contain the offset (from the segment address in DS) 
of the Disk Transfer Address. Disk transfers cannot wrap 
around from the end of the segment to the beginning, nor can 
they overflow into another segment. 


A 


NOTE 


If you do not set the Disk 
Transfer Address, MS-DOS 
defaults to offset 88H in the 
Program Segment Prefix. 


Macro Definition: set dta macro buffer 


mov dx,offset buffer 
mov ah,1lAH 

int 21H 

endm 


Example 


The following program prompts for a letter, converts’ the 
letter to its alphabetic sequence (A = 1, B = 2, etc.), then 
reads and displays the corresponding record from a_ file 
named ALPHABET.DAT on the disk in drive B:. The file 
contains 26 records; each record is 28 bytes long: 


record size equ 14 ;offset of Record Size 
;field of FCB 
relative record equ 33 ;offset of Relative Record 


;field of FCB 


. 


SYSTEM CALLS 


te, 


fcb 


buffer 
prompt 
erlf 


func_1AH: 


get_char: 


all_done: 
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db 2," ALPHABETDAT" 
db 25 dup (?) 
db 34 dup(?),"s" 
db "Enter letter: §" 
db 13,190,"$" 
set dta buffer sTHIS FUNCTION 
open fcb ssee Function @FH 
mov feb[record size],28 ;set record size 
display prompt ssee Function 99H 
read_kbd_and_echo ;see Function 91H 
cmp al,@DH just a CR? 
je all_done syes, go home 
sub al,41H sconvert ASCII 

s;code to record # 
mov fcb[relative record] ,al 

~sset relative record 

display crlf ssee Function 99H 
read ran fcb ssee Function 21H 
display buffer ssee Function 99H 
display crlf ssee Function @9H 
jmp get_char sget another character 
close f£cb ;see Function 19H 
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Random Read (Function 21H) 


Call 
AH = 21H 
DS:DX 
Opened FCB 
Return 
AL 
O@@H = Read completed successfully 
@1H = EOF 
@2H = DTA too small 
@3H = EOF, partial record 


DX must contain the offset (from the segment address in DS) 
of an opened FCB. The Current Block (offset @CH) and 
Current Record (offset 20H) fields are set to agree with the 
Relative Record field (offset 21H), then the record 
addressed by these fields is loaded at the Disk Transfer 
Address. 


AL returns a code that describes the processing: 


Code Meaning 

4] Read completed successfully. 

1 End-of-file; no data in the record. 

2 Not enough room at the Disk Transfer Address 


to read one record; read canceled. 


3 End-of-file; a partial record was read and 
padded to the record length with zeros. 


Macro Definition: read_ran macro fcb 


mov dx,offset fcb 
mov ah,21H 

int 21H 

endm 


Example 


The following program prompts for a letter, converts’ the 
letter to its alphabetic sequence (A = 1, B = 2, etc.), then 
reads and displays the corresponding record from a _ file 
named ALPHABET.DAT on the disk in drive B:. The file 
contains 26 records; each record is 28 bytes long: 


SYSTEM CALLS 


record size equ 


relative record equ 


Random Read Page 


14 ;offset of Record Size 


;field of FCB 


33 soffset of Relative Reco 


;field of FCB 


fcb db 2," ALPHABETDAT" 
db dup (?) 

buffer db 34 dup(?),"s" 

prompt db "Enter letter: $" 

crlf db 13,10,"$" 

func _21H: set dta buffer ;see Function 
open fcb ssee Function 


mov 
get char: 


cmp 
je 
sub 


mov 


display 
“ read ran 
display 
display 


jmp 
all_ done: close 


display prompt 
read_kbd_and_echo 


fcb[record size],28 ;set record 
;see Function 
ssee Function 


al,@DH sjust a CR? 
all_ done syes, go home 
al,41H sconvert ASCII 


sto record # 
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rd 


1AH 
OFH 
size 
09H 
G1H 


code 


feb[relative_record],al ;set relative 


;record 
crlf ssee Function @9H 
fcb ;THIS FUNCTION 
buffer s;see Function 99H 
crlf ;see Function @9H 
get_char ;get another char. 


fcb ;see Function 


19H 


SYSTEM CALLS Random Write Page 1-74 


Random Write (Function 22H) 


Call 
AH = 22H 
DS:DX 
Opened FCB 
Return 
AL 
QGH = Write completed successfully 
1H = Disk full 
82H = DTA too small 


DX must contain the offset from the segment address in DS of 
an opened FCB. The Current Block (offset OCH) and Current 
Record (offset 2@H) fields are set to agree with the 
Relative Record field (offset 21H), then the record 
addressed by these fields is written from the Disk Transfer 
Address. If the record size is smaller than a sector (512 
bytes), the records are buffered until a sector is ready to 
write. 


AL returns a code that describes the processing: 


Code Meaning 
i) Write completed successfully. 
1 Disk is full. 
2 Not enough room at the Disk Transfer Address 


to write one record; write canceled. 


Macro Definition: write ran macro fcb 


mov dx,offset fcb 
mov ah,22H 

int © 21H 

endm 


Example 


The following program prompts for a letter, converts’ the 
letter to its alphabetic sequence (A = 1, B = 2, etc.), then 
reads and displays the corresponding record from a file 
named ALPHABET.DAT on the disk in drive B:. After 
displaying the record, it prompts the user to enter a 
changed record. If the user types a new record, it is 


SYSTEM CALL 


written to 
record isn 
record is 2 
record size 


relative re 


fcb 


buffer 
promptl 
prompt2 
erlf 
reply 
blanks 


func _22H: 


get_char: 


all_ done: 
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the file; if the user just presses RETURN, the 
ot replaced. The file contains 26 records; each 
8 bytes long: 


equ 14 ;offset of Record Size 
;field of FCB 
cord equ 33 soffset of Relative Record 


sfield of FCB 


db 2,"ALPHABETDAT" 

db 25 dup (?) 

db 26 dup(?),13,10,"5" 

db "Enter letter: §$" 

db "New record (RETURN for no change): §$" 
dab 13,1¢,"s" 

db 28 dup (32) 

db 26 dup (32) 


set dta buffer ssee Function 1AH 
open fcb ssee Function @FH 
mov feb[record size],32 ;set record size 
display promptl ;see Function 69H 
read_kbd_and_echo ;see Function §1H 
cmp “al ,@DH ;just a CR? 
je all_done syes, go home 
sub al,41H sconvert ASCII 
scode to record # 
mov feb[relative_record], al 
;set relative record 
display crlf ssee Function 99H 
read ran fcb s;THIS FUNCTION 
display buffer ;see Function 99H 
display crlf ssee Function 99H 
display prompt2 ;see Function 69H 
get_string 27,reply ssee Function @AH 
display crlf ;see Function 9H 
emp reply[(1],0 swas anything typed 
sbesides CR? 
je get_char 7no 
;get another char. 
XOX bx ,bx sto load a byte 
mov bl,reply[1] suse reply length as 
scounter 


move string blanks, buffer,26 ;see chapter end 
move string reply [2], puffer, bx ;see chapter end 
write_ ran fcb : THIS FUNCTION 

jmp get_char ;get another character 
close Ecb ;see Function 10H 
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File Size (Function 23H) 


Call 
AH = 23H 
DS:DX 
Unopened FCB 


@@H = Directory entry found 
FFH (255) = No directory entry found 


DX must contain the offset (from the segment address in DS) 
of an unopened FCB. You must set the Record Size field 
(offset @EH) to the proper value before calling this 
function. The disk directory is searched for the first 
matching entry. 


If a matching directory entry is found, the Relative Record 
field (offset 21H) is set to the number of records in the 
file, calculated from the total file size in the directory 
entry (offset 1CH) and the Record Size field of the FCB 
(offset OEH). AL returns @@. 


If no matching directory is found, AL returns FFH (255). 


NOTE 


If the value of the Record 
Size field of the FCB (offset 
QEH) doesn't match the actual 
number of characters in a 
record, this function does not 
return the correct file size. 
If the default record size 
(128) is not correct, you must 
set the Record Size field to 
the correct value before using 
this function. 


SYSTEM CALLS 


Macro Definition: file size macro 
= mov 
mov 
int 
endm 


Example 


The following program prompts for the name of a file, 


File Size 
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fcb 

dx,offset fcb 
ah,23H 

21H 


opens 


the file to fill in the Record Size field of the FCB, issues 


a File Size system call, and displays 


number of records in hexadecimal: 


fcb db 37 dup (?) 
prompt db "File name: §" 
msgl db "Record length: 
msg2 db "Records: 
erlf db 13,10,"S" 
reply db 17 dup(?) 
sixteen db 16 
func_23H: display prompt 

get_string 17,reply 

cmp reply{1] ,@ 

‘ jne get_length 

jmp all_done 
get_length: display crlf 

parse reply[2],fcb 

open fcb 

file size fcb 

mov si,33 

mov di,9 
convert_it: cmp fcb[si] ,@ 

je show it 

convert 

inc si 

inc di 

jmp convert it 
show_it: convert 


display msg 1 
display msg 2 
jmp func_23H 


all_ done: close fcb 


the file size and 


",13,10,"S" 
",13,10,"S" 


ssee Function 99H 
ssee Function OAH 
;just a CR? 

sno, keep going 
;yes, go home 

ssee Function 99H 
;see Function 29H 
;see Function OFH 
;THIS FUNCTION 
soffset to Relative 
;Record field 
;reply in msg_2 
sdigit to convert? 
;no, prepare message 


feb[si] ,sixteen,msg_2[di] 


sbump n-o-r index 
sbump message index 
scheck for a digit 


feb[{14],sixteen,msg_1[15] 


Function @9H 
Function 99H 
a filename 

Function 1@H 


;see 
;see 
get 
7see 
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Set Relative Record (Function 24H) 


Call 
AH = 24H 
DS:DX 

Opened FCB 


Return 
None 


DX must contain the offset (from the segment address in DS) 
of an opened FCB. The Relative Record field (offset 21H) is 
set to the same file address as the Current Block (offset 
@CH) and Current Record (offset 20H) fields. 


Macro Definition: set_relative_record macro  fcb 


mov dx,offset fcb 
mov ah,24H : 
int 21H 

endm 


Example 


The following program copies a file using the Random _ Block 
Read and Random Block Write system calls. It speeds the 
copy by setting the record length equal to the file size and 
the record count to 1, and using a buffer of 32K bytes. It 
positions the file pointer by setting the Current Record 
field (offset 20H) to 1 and using Set Relative Record to 
make the Relative Record field (offset 21H) point to _ the 
same record as the combination of the Current Block (offset 
@CH) and Current Record (offset 20H) fields: 


current _record equ 32 ;offset of Current Record 
;field of FCB 
file size equ 16 ;offset of File Size 


sfield of FCB 


fcb db 37 dup (?) 

filename db 17 dup(?) 
promptl db "File to copy: S$" ;see Function @9H for 
prompt2 db "Name of copy: S$" j;explanation of $ 


crlf db 13,18,"S" 
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file length dw ? 


buffer db 32767 dup(?) 
func_24H: set_dta buffer ;see Function l1AH 
display promptl ssee Function 69H 
get_string 15,filename ;see Function @AH 
display crlf ssee Function 99H 
parse filename[2] ,fcb ssee Function 29H 
open fcb ;see Function 9FH 
mov feb[current_record] ,@ ;set Current Record 
sfield 
set_relative record fcb sTHIS FUNCTION 
mov ax,word ptr fcb[file size] ;get file size 
mov file length,ax ssave it for 
2 ;ran_block write 
ran block_read fcb,l,ax ;see Function 27H 
display prompt2 ssee Function @9H 
get string 15,filename ssee Function @AH 
display crlf ssee Function 99H 
parse filename[(2] ,fcb ssee Function 29H 
create fcb ssee Function 16H 
mov fcb[current_record] ,@ ;set Current Record 
;field 
set relative record fcb ;THIS FUNCTION 
5 mov ax,file_length sget original file 
slength 
ran_block write fcb,1l,ax ssee Function 28H 


close fcb ssee Function 16H 
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Set Vector (Function 25H) 


Call 
AH = 25H 
AL 
Interrupt number 
DS :DxX 
Interrupt-handling routine 


Return 
None 


Function 25H should be used to set a particular interrupt 
vector. The operating system can then manage the interrupts 
on a per-process basis. Note that programs should never set 
interrupt vectors by writing them directly in the low memory 
vector table. 


DX must contain the offset (to the segment address in DS) of 
an interrupt-handling routine. AL must contain the number 
of the interrupt handled by the routine. The address in the 
vector table for the specified interrupt is set to DS:DX. 


Macro Definition: 
set_vector macro interrupt,seg addr,off addr 


mov al,interrupt 
push ds 
mov ax,seg addr 
mov ds,ax 
mov dx,off addr 
mov ah,25H ~ 
int 21H 
pop ds 
endm 

Example 

lds dx,intvector 

mov ah,25H 

mov al, intnumber 

int 21H 


;There are no errors returned 


| 
| 
| 


SYSTEM CALLS Random Block Read Page 1-81 


Random Block Read (Function 27H) 


Call 
AH = 27H 
DS:DX 
Opened FCB 
CX 
Number of blocks to read 


Return 
AL 
OOH = Read completed successfully 
@1H = EOF 
@2H = End of segment 
@3H = EOF, partial record 
CX 


Number of blocks read 


DX must contain the offset (to the segment address in DS) of 
an opened FCB. CX must contain the number of records to 
read; if it contains @, the function returns without 
reading any records (no operation). The specified number of 
records -- calculated from the Record Size field (offset 
@EH) -- is read starting at the record specified by the 
Relative Record field (offset 21H). The records are placed 
at the Disk Transfer Address. 


AL returns a code that describes the processing: 


Code Meaning 
g Read completed successfully. 
1 End-of-file; no data in the record. 
2 Not enough room at the Disk Transfer Address 


to read one record; read canceled. 


3 End-of-file; a partial record was read 
and padded to the record length with zeros. 


CX returns the number of records read; the Current Block 
(offset @CH), Current Record (offset 20H), and Relative 
Record (offset 21H) fields are set to address the next 
record. 
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Macro Definition: 
ran_block_ read macro fcb,count,rec_size 


mov dx,offset fcb 

mov cx,count 

mov word ptr fcb[14],rec size 
mov ah,27H - 

int 21H 

endm 


Example 


The following program copies a file using the Random Block 
Read system call. It speeds the copy by specifying a record 
count of 1 and a record length equal to the file size, and 
using a buffer of 32K bytes; the file is read as a single 
record (compare to the sample program for Function 28H that 
specifies a record length of 1 and a record count equal to 
the file size): 


current record equ 32 soffset of Current Record field 


file size equ 16 soffset of File Size field 
fcb db 37 dup (?) 
filename db 17 dup(?) 
promptl db "File to copy: §" ;see Function 99H for 
prompt2 db "Name of copy: $s" sexplanation of §$ 
crlft db 13,10,"S$" 
file length dw ? 
buffer db 32767 dup(?) 
func_27H: set_dta buffer ssee Function 1AH 
display promptl ;see Function @9H 
get_string 15,filename ;see Function @AH 
display crlf ;see Function @9H 
parse filename[2]),fcb ;see Function 29H 
open fcb ;see Function @OFH 
mov fceb[current_record],@ ;set Current 
;Record field 
set_ relative record fcb ;see Function 24H 
mov ax, word ptr feb[file_ size] 
sget file size 
mov file length,ax ;save it for 
a ;xan_block_write 
ran_block_ read fcb,1l,ax. . sTHIS FUNCTION 
display prompt2 ;see Function 99H 
get_string 15,filename ;see Function @AH 
display crlft ;see Function @9H 
parse filename[2],fcb- ;see Function 29H 
create fcb s;see Function 16H 
mov fcb[current record] ,@ 
sset Current Record 
;field 


set_ relative record fcb s;see Function 24H 
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{ ) mov ° ax, file length j;get original file 
;size 

ran_block write fcb,1,ax ;see Function 28H 

close fcb ssee Function 16H 
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Random Block Write (Function 28H) 


Call 

AH = 28H 

DS:DX 
Opened FCB 

CX 
Number of blocks to write 
(@ = set File Size field) 


Return 

AL 
QOH = Write completed successfully 
@1H = Disk full 
@2H = End of segment 

CX 


Number of blocks written 


DX must contain the offset (to the segment address in DS) of 
an opened FCB; CX must contain either the number of records 
to write or @. The specified number of records (calculated 
from the Record Size field, offset @EH) is written from the 
Disk Transfer Address. The records are written to the file 
starting at the record specified in the Relative Record 
field (offset 21H) of the FCB. If CX is @, no records are 
written, but the File Size field of the directory entry 
(offset 1CH) is set to the number of records specified by 
the Relative Record field of the FCB (offset 21H); 
allocation units are allocated or released, as required. 


AL returns a code that describes the processing: 


Code Meaning 
i) Write completed successfully. 
1 . Disk full. No records written. 
2 Not enough room at the Disk Transfer Address 


to read one record; read canceled. 


CX returns the number of records written; the Current Block 
(offset @CH), Current Record (offset 29H), and Relative 
Record (offset 21H) fields are set to address the next 
record. 


a 
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Macro Definition: 
ran_block write macro fcb,count,rec size 


mov dx,offset fcb_ 

mov ecx,count 

mov word ptr fcb[14], rec_ size 
mov ah,28H 

int 21H 

endm 


Example 


The following program copies a file using the Random Block 
Read and Random Block Write system calls. It speeds the 
copy by specifying a record count equal to the file size and 
a record length of 1, and using a buffer of 32K bytes; the 
file is copied quickly with one disk access each to read and 
write (compare to the sample program of Function 27H, that 
specifies a record count of 1 and a record length equal to 
file size): 


current_record equ 32 ;offset of Current Record field 
file size equ 16 soffset of File Size field 
fcb db 37 dup (?) 
filename db 17 dup(?) 
promptl db "File to copy: $" ;see Function @9H for 
prompt2 db "Name of copy: $s" sexplanation of $ 
crlft db a 19,"S" 
num_recs dw 
buffer db foe dup (?) 
func _28H: set dta buffer ssee Function 1AH 
display promptl ssee Function 99H 
get_string 15,filename ;see Function AH 
display crlf ;see Function @9H 
parse filename[2],fcb ;see Function 29H 
open f£cb ;see Function @FH 
mov feb{current record] ,@ 
set Current Record 
;field 
set_ relative record fcb ;see Function 24H 
mov aX, word ptr fcb[file size] 
sget file size 
mov num_recs,ax ssave it for 


;ran_block_write 
ran_block_read fcb,num_recs,1 ZTHIS FUNCTION 


display prompt2 ;see Function 99H 
get_string 15,filename ssee Function @AH 
display erlf ;see Function 69H 
parse filename[2],fcb ;see Function 29H 
create fcb ;see Function 16H 
mov feb[current_ record],@ ;set Current 


Record field 
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set relative record fcb ;see Function 24H 
mov - ax, file length j;get size of original 
ran_block_ write fcb,num_recs,1 ;see Function 28H 
close ~ feb ssee Function 10H 
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Parse File Name (Function 29H) 


Call 
AH = 29H 
AL 
Controls parsing (see text) 
a DS:SI 
String to parse 
ES:DI 
| Unopened FCB 
Return 
AL 
@GH = No wild card characters 
@1H = Wild-card characters used 
FFH (255) = Drive letter invalid 
DS:SI 
First byte past string that was 
parsed 
ES:DI 


Unopened FCB 


SI must contain the offset (to the segment address in DS) of 
a string (command line) to parse; DI must contain the 
offset (to the segment address in ES) of an unopened FCB. 
The string is parsed for a filename of the form 
d:filename.ext; if one is found, a corresponding unopened 
FCB is created at ES:DI. 


Bits @-3 of AL control the parsing and processing. Bits 4-7 
are ignored: 


Bit Value Meaning 


i] g All parsing stops if a file separator is 
encountered. 
il Leading separators are ignored. 
1 G The drive number in the FCB is set to @ 


(default drive) if the string does not 
contain a drive number. 


1 The drive number in the FCB is not changed 
if the string does not contain a drive 
number. 

2 af The filename in the FCB is not changed if 
the string does not contain a filename. 

@ The filename in the FCB is set to 8 blanks 
if the string does not contain a filename. 

3 1 The extension in the FCB is not changed 
if the string does not contain an extension. 
g The extension in the FCB is set to 3 blanks 


if the string does not contain an extension. 
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If the filename or extension includes an asterisk (*), all 
remaining characters in the name or extension are set to 
question mark (?). 


Filename separators: 
a a a a i a | space tab 


Filename terminators include all the filename separators 
plus any control character. A filename cannot contain a 
filename terminator; if one is encountered, parsing stops. 


If the string contains a valid filename: 


1. AL returns 1 if the filename or extension contains 
a wild card character (* or ?); AL returns @ if 
neither the filename nor extension contains a wild 
card character. 


2. DS:SI point to the first character following’ the 
string that was parsed. 


ES:DI point to the first byte of the unopened FCB. 


~ 


If the drive letter is invalid, AL returns FFH (255). If 
the string does not contain a valid filename, ES:DI+1l points 
to a blank (ASCII 32). 


Macro Definition: parse macro string,fcb 
mov si,offset string 
mov di,offset fcb 


push es 
push ds 
pop es 


mov al,@FH ;bits @, 1, 2, 3 on 
mov ah,29H 


int 21H 
pop es 
endm 


Example 


The following program verifies the existence of the file 
named in reply to the prompt: 


fcb db 37 dup (?) 

prompt db "Filename: §" 

reply db 17 dup(?) 

yes db "FILE EXISTS",13,16,"$" 


no db "FILE DOES NOT EXIST" ,13, 16, nge 
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func_29H: display prompt ;see Function 99H 
get_string 15,reply ;see Function @AH 
parse reply[2]),fcb ;THIS FUNCTION 
search first fcb ;see Function 11H 
cmp al,FFH sdir. entry found? 
je ' not_there ;no 
display yes ssee Function @9H 
jmp continue 

not_there: display no 


continue: ‘ 


e » 
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Get Date (Function 2AH) 


Year (1988 - 2999) 
DH 
Month (1 —- 12) 
DL 
Day (1 - 31) 
AL 
Day of week (@=Sun., 6=Sat.) 


This function returns the current date set in the operating 
system as binary numbers in CX and DX: 


CX Year (1988-2899) 


DH Month (1 = 
DL Day (1-31) 


AL Day of week (@ 


January, 2 = February, etc.) 


= Sunday, 1 = Monday, etc.) 


Macro Definition: get_date macro 


Example 


mov ah, 2AH 
int 21H 
endm 


The following program gets the date, increments the day, 
increments the month or year, if necessary, and sets the new 


date: 

month db 31,28,31,39,31,398,31,31,38,31,38,31 

func 2AH: get date ;see above 

~ inc dl ;increment day 

xor bx , bx sso BL can be used as index 
mov bl,dh ;move month to index register 
dec bx smonth table starts with @ 
cmp dl,month{bx] ;past end of month? 
jle month ok sno, set the new date 
mov dis... yes, set day to l 
inc dh sand increment month 
cmp dh,12 tpast end of year? 
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( jle’ month_ok sno, set the new date 
/ mov dh,l ;yes, set the month to 1 
inc cx ;increment year 


month_ok: set date cx,dh,dl :THIS FUNCTION 
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Set Date (Function 2BH) 


Year (1988 - 2999) 
Month (1 - 12) 


Day (1 - 31) 


@@H = Date was valid 
FFH (255) = Date was invalid 


Registers CX and DX must contain a valid date in binary: 


CX Year (1989-2099) 
DH Month (1 = January, 2 = February, etc.) 
DL Day (1-31) 


If the date is valid, the date is set and AL returns @. If 
the date is not valid, the function is canceled and AL 
returns FFH (255). 


Macro Definition: set_date macro year,month,day 


mov cx,year 
mov dh ,month 
mov dl,day 
mov ah, 2BH 
int 21H 

endm 


Example 


The following program gets the date, increments the day, 
increments the month or year, if necessary, and sets the new 
date: 


month db 31,28,31,39,31,30,31,31,38,31,308,31 
func_2BH: get date ;see Function 2AH 
inc dl :increment day 
XOLr bx,bx ;s0 BL can be used as index 
mov bl,dh ;move month to index register 
dec bx smonth table starts with @ 


cmp dl,month[{bx] ;past end of month? 
jle month_ok sno, set the new date 


SYSTEM CALLS 


month_ok: 


mov’ dl,l 

inc dh 

cmp dh,12 

jle month_ok 
mov dh,l 

inc cx 
set_date cx,dh,dl 
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syes, set day to 1 

sand increment month 
;past end of year? 

sno, set the new date 
syes, set the month to 1 
;increment year 

;THIS FUNCTION 
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Get Time (Function 2CH) 


Hour (@ - 23) 
CL 

Minutes (@ =~ 59) 
DH 

Seconds (@ - 59) 
DL 
Hundredths (@ - 99) 


This function returns the current time set in the operating 
system as binary numbers in CX and DX: 


CH Hour (9-23) 


DL Hundredths of a second (8-99) 


Macro Definition: get_time macro 
mov ah,2CH 
int 21H 
endm : 


Example 


The following program continuously displays the time until. 
any key is pressed: 


time db "908:00:00.00",13,10,"5S" 

ten db 18 

func_2CH: get_time ;THIS FUNCTION 
convert ch,ten,time z;see end of chapter 


convert cl,ten,time[3] ;see end of chapter 
convert dh,ten,time[6] ;see end of chapter 
convert dl,ten,time[9] ;see end of chapter 


display time ssee Function 99H 

check kbd status ;see Function @BH 

cmp - al,FFH shas a key been pressed? 
je all done syes, terminate 


jmp func _2CH ;no, display time 
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Set Time (Function 2DH) 


FREER 


Hour (8 - 23) 
CL 

Minutes (@ - 59) 
DH . 
Seconds (@ - 59) 
DL 


pe 

pe 

a eee 

ears 

eae Hundredths ( - 99) 
L Fuagsn | FLAGS. | 

ae aes 

ae ae 

[ss 

ee ee 


Return 
AL 
90H = Time was valid 
FFH (255) = Time was invalid 


Registers CX and DX must contain a valid time in binary: 


CH Hour (98-23) 

CL Minutes (08-59) 

DH Seconds (@-59) 

DL Hundredths of a second (8-99) 


If the time is valid, the time is set and AL returns @. If 
the time is not valid, the function is canceled and AL 


‘returns FFH (255). 


Macro Definition: 
set_time macro hour ,minutes,seconds ,hundredths 


mov ch,hour 
mov cl,minutes 
mov dh,seconds 


mov dl,hundredths 
mov ah, 2DH 

int 21H 

endm 


Example 


The following program sets the system clock to §@ and 
continuously displays the time. When a character is typed, 
the display freezes; when another character is typed, the 
clock is reset to @ and the display starts again: 


time db "99:00:09.006",13,10,"S" 
ten db 10 
func 2DH: set time 0,0,0,9 ;THIS FUNCTION 


read clock: get_time :see Function 2CH 


SYSTEM CALLS 


stop: 


Set Time 


convert ch,ten,time 
convert cl,ten,time[3] 
convert dh,ten,time[6] 
convert dl,ten,time([9] 
display time 

dir console io FFH 


cmp al,@@H 

jne stop 

jmp read_ clock 
read_kbd 


jmp func _2DH 


ssee 
;see 
;see 
s;see 
see 
see 
;was 
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end of chapter 
end of chapter 
end of chapter 
end of chapter 
Function 99H 

Function @6H 

a char. typed? 


syes, stop the timer 
7no keep timer on 


ssee 


Function @8H 


skeep displaying time 


| 
| 
f 
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Set/Reset Verify Flag (Function 2EH) 


Call 

i AH = 2EH 

| AL 

@@H = Do not verify 
91H = Verify 

| 

| 

(| Return 

| None 


AL must be either 1 (verify after each disk write) or @ 
(write without verifying). MS-DOS checks this flag each 
time it writes to a disk. 


The flag is normally off; you may wish to turn it on when 
writing critical data to disk. Because disk errors are rare 
and verification slows writing, you will probably want to 
leave it off at other times. 


Macro Definition: verify macro switch 


mov al,switch 
mov ah, 2EH 
int 21H 

endm 


Example 


The following program copies the contents of a_ single-sided 
disk in drive A: to the disk in drive B:, verifying each 
write. It uses a buffer of 32K bytes: 


on equ 1 

off equ i] 

prompt db “Source in A, target in B",13,19 
db "Any key to start. §" 

start dw 1] 

buffer db 64 dup (512 dup(?)) 364 sectors 

func _2DH: display prompt ;see Function 99H 
read_ kbd ;see Function @8H 


verify on ;THIS FUNCTION | 


SYSTEM CALLS 


copy: 


disk_ read 
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mov cx,5 ;copy 64 sectors 
75 times 
push cx ;save counter 


abs disk read 9,buffer,64,start 

oe o ;see Interrupt 25H 
abs disk write 1,buffer,64,start 

is > ;see Interrupt 26H 


add start,64 ;do next 64 sectors 
pop cx ;restore counter 
loop copy ;do it again 

verify off ;THIS FUNCTION 
@,buffer,64,start ;see Interrupt 25H 


abs disk write 1,buffer,64,start 
;see Interrupt 26H 


add start,64 ;do next 64 sectors 
pop cx ;restore counter 
loop copy ;do it again 


verify off 
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Get Disk Transfer Address (Function 2FH) 


Call 
AH = 2FH 


Return 
ES:BX 
Points to Disk Transfer Address 


Function 2FH returns the DMA transfer address. 


Error returns: 


( . None. 


Example 
mov ah, 2FH 
int 21H 


;es:bx has current DMA transfer address 
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Get DOS Version Number (Function 36H) 


Call 
AH = 36H 


Return 
AL 

Major version number 
AH 

Minor version number 


This function returns the MS-DOS version number. On return, 
AL.AH will be the two-part version designation; i.e., for 
MS-DOS 1.28, AL would be 1 and AH would be 28. For 
pre-1.28, DOS AL = @. Note that version 1.1 is the same as 
1.18, not the same as 1.91. 


Error returns: 


None. 
Example 
mov ah,3@H 
int 21H 


al is the major version number 

ah is the minor version number 

bh is the OEM number 

bls:cx is the (24 bit) user number 


me me MO MO 
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Keep Process (Function 31H) 


Exit code 
| DX 
Memory size, in paragraphs 


Return 


[ 
ee od 

fe Oe 
To 
[* ] None 
[Faas | FLAGS: 
a 

[os _ 

ar ee 

ee ee 


This call terminates the current process and attempts to set 
the initial allocation block to a specific size in 
paragraphs. It will not free up any other allocation blocks 
belonging to that process. The exit code passed in AX is 
retrievable by the parent via Function 4DH. 


This method is preferred over Interrupt 27H and has’ the 
advantage of allowing more than 64K to be kept. 


Error returns: 


None. 
Example 
mov al, exitcode 
mov dx, parasize 
mov ah, 31H 


int 21H 
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CONTROL-C Check (Function 33H) 


Function 
@@H = Request current state 
§1H = Set state 


ae eee 
eee eae ; i 
Sere: igh ca eee 
anes eae Pifices Ga 
ae eel 


Return 
| cS DL 
a. ee GH = OfE 
Rae ee @1H = On 
FS 


MS-DOS ordinarily checks for a CONTROL-C on the controlling 
device only when doing function call operations 91H-@CH to 
that device. Function 33H allows the user to expand this 
checking to include any system call. For example, with the 
CONTROL-C trapping off, all disk I/O will proceed without 
interruption; with . CONTROL-C trapping on, the CONTROL-C 
interrupt is given at the system call that initiates the 
disk operation. 


NOTE 


Programs that wish to use 
calls @6H or @7H to read 
CONTROL-Cs as data must ensure 
that the CONTROL-C' check is 
off. 


Error returns: 


AL = FF 
The function passed in AL was not in the range 
O31. 
Example 
mov dl,val 
mov ah,33H 


mov al,func 
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int 21H 
\ / If al was @, then dl has the current value 
of the CONTROL-C check 


. 
a 
e 
Lf 
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Get Interrupt Vector (Function 35H) 


Interrupt number 


Return 
ES :BX 
Pointer to interrupt routine 


This function returns the interrupt vector associated with 
an interrupt. Note that programs should never’ get an 
interrupt vector by reading the low memory vector table 
directly. 


Error returns: 


None. 
Example 
mov ah,35H 
mov al,interrupt 
int 21H 


7 es:bx now has long pointer to interrupt routine 


SYSTEM CALLS 


eit, 


RRR ® 


Te 

[ ~d Available clusters 
| FLAGSH |] FLAGS. 

Ts 

TS 
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Get Disk Free Space (Function 36H) 


Drive ( @ = Default, 
1 = A, etc.) 


Return 
BX 


Dx 
Clusters per drive 
CX 
Bytes per sector 
AX 
FFFF if drive number is invalid; 
otherwise sectors per cluster 


This function returns free space on disk along with 


additional information about the disk. 


Error returns: 
FEFFE — 


AX = 
Example 


mov 
mov 


=e %O TO NO 


bx 
ax 
cx 
ax 


The drive number given in DL was invalid. 


ah ,36H 

dl,Drive ;0 = default, A=l 

21H 
Number of free allocation units on drive 


Total number of allocation units on drive 
Bytes per sector 
Sectors per allocation unit 


SYSTEM CALLS Return Ctry-Dependent Info Page 1-196 


Return Country-Dependent Information (Function 38H) 


Call 
AH = 38H 
DS:DX 
| Pointer to 32-byte memory area 
AL 
Function code. In MS-DOS 2.6, 
must be @g 


Return 
Carry set: 
AX 
2 = file not found 
Carry not set: 
DX:DS filled in with country data 


The value passed in AL is either @ (for current country) or 
a country code. Country codes are typically the 
international telephone prefix code for the country. 


If DX = -1, then the call sets the current country (as 
returned by the AL=@ call) to the country code in AL. If 
the country code is not found, the current country is not 
changed. 


NOTE 


Applications must assume 32 
bytes of information. This 
means the buffer pointed to by 
DS:DX ° must be able to 
accommodate 32 bytes. 


This function is fully supported only in versions of MS-DOS 
2.91 and higher. It exists in MS-DOS 2.9, but is not fully 
implemented 


This function returns, in the block of memory pointed to by 
DS:DX, the following information pertinent to international 
applications: 
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WORD Date/time format 
5 BYTE ASCIZ string 
currency symbol 

2 BYTE ASCIZ string 
thousands separator 

2 BYTE ASCIZ string 
decimal separator 

2 BYTE ASCIZ string 
date separator 

2 BYTE ASCIZ string 
time separator 

1 BYTE Bit field 

1 BYTE 

Currency places 

l BYTE 

time format 
DWORD 

Case Mapping call 

2 BYTE ASCIZ string 
data list separator 


The format of most of these entries is ASCIZ (a NUL 
terminated ASCII string), but a fixed size is allocated for 
each field for easy indexing into the table. 


—— 


The date/time format has the following values: 


- USA standard h:m:s m/d/y 
- Europe standard h:m:s d/m/y 
- Japan standard y/m/d h:m:s 


NES 


The bit field contains 8 bit values. Any bit not currently 
defined must be assumed to have a random value. 


Bit @ = @ If currency symbol precedes the 
currency amount. 
= 1 If currency symbol comes after 
the currency amount. 
Bit 1 If the currency symbol immediately 
fae \ precedes the currency amount. 
= 1 If there is a space between the 
| currency symbol and the amount. 


u 
Q 
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The time format has the following values: 


@ - 12 hour time 
1 - 24 hour time 


The currency places field indicates the number of places 
which appear after the decimal point on currency amounts. 


The Case Mapping call is a FAR procedure which will perform 
country specific lower-to-uppercase mapping on character 
values from 8@H to FFH. It is called with the character to 
be mapped in AL. It returns the correct upper case code for 
that character, if any, in AL. AL and the FLAGS are’ the 
only registers altered. It is allowable to pass this 
routine codes below 8s@H; however nothing is done to 
characters in this’ range. In the case where there is no 
mapping, AL is not altered. 


Error returns: 


AX 
2 = file not found 
The country passed in AL was not found (no 
table for specified country). 
Example 
lds ax, blk 
mov ah, 38H 
mov al, Country code 
int 21H 


;AX = Country code of country returned 
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? Create Sub-Directory (Function 39H) 


hot fm | Call 

| en | om {| AH = 39H 
fF oceH | c& _} DxX:DS 
co] = 


Pointer to pathname 


ZL" ® 


3 = path not found 
5 = access denied 
Carry not set: 
No error 


Given a pointer to an ASCIZ name, this function creates a 
new directory entry at the end. 


Error returns; 


a AX 
tb | 3. = path not found 
~ = The path specified was invalid or not found. 


5 = access denied 
The directory could not be created (no room in 
parent directory), the directory/file already 
existed or a device name was specified. 
Example 
lds dx, name 
mov ah, 39H 


int 21H 


SYSTEM 


Remove 


CALLS 


Call 
AH = 3AH 
DS:DX 


Return 
Carry set: 


No error 
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a Directory Entry (Function 3AH) 


Pointer to pathname 


path not found 
access denied 

16 = current directory 
Carry not set: 


Function 3AH is given an ASCIZ name of a directory. That 
directory is removed from its parent directory. 


Error 


AX 
3 


5 


16 


Example 


lds 
mov 
int 


returns: 


path not found 


The path specified was invalid or not found. 


access denied 
The path specified 
directory, the root 
invalid information. 
current directory 
The path specified 
on a drive. 


dx, name 
ah, 3AH 
21H 


was not empty, not a 
directory, or contained 


was the current directory 


SYSTEM CALLS 


RRER 


Function 3BH is given the ASCIZ name of 
the current directory. 
does 


is to 


become 


Change Current Directory 


specified pathname 


directory is unchanged. 


c set to the string. 


Error returns: 


AX 


Change the Current Directory (Function 3BH) 


Call 
AH = 3BH 
DS:DX 
Pointer to pathname 


Return 
Carry set; 
AX 
3 = path not found 
Carry not set: 
No error 


not exist, 


3 = path not found 
The path specified in DS:DX either indicated a 
file or the path was invalid. 


Example 


lds 
mov 
int 


dx, 
ah, 
21H 


name 
3BH 
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the directory which 
If any member of the 
then 
Otherwise, the current directory is 


current 
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Create a File (Function 3CH) 


Call 
AH = 3CH 
DS:DX 
‘Pointer to pathname 
CX 
File attribute 


Return 
Carry set: 
AX 
= access denied 
3 = path not found 
= too many open files 
Carry not set: 
AX is handle number 


Function 3CH creates a new file or truncates an old file to 
zero length in preparation for writing. If the file did not 
exist, then the file is created in the appropriate directory 
and the file is given the attribute found in CX. The file 
handle returned has been opened for read/write access. 


Error returns: 
AX 
5 = access denied 

The attributes specified in CX contained one 
that could not be created (directory, volume 
ID), a file already existed with a more 
inclusive set of attributes, or a directory 
existed with the same name. 


3 = path not found 
The path specified was invalid. 

4 = too many open files 
The file was created with’ the specified 
attributes, but there were no free handles 
available for the process, or the internal 
system tables were full. 

Example 

lds dx, name 

mov ah, 3CH 

mov cx, attribute 

int 21H 


; ax now has the handle 


SYSTEM CALLS Open a File Page 1-113 


Open a File (Function 3DH) 


- Eu tT «) Call 
ie AH = 3DH 
se als 
cx: 
§@ = File opened for reading 
ee aaa 1 = File opened for writing 
ea eee 2 = File opened for both 
zz Sas reading and writing 
a 
PS ia ; ot | ek 
ps —*d 12 = invalid access 4 Path pot fuk 
| ss +4 2 = file not found 
Yes | 5 = access denied 
4 = too many open files 


Carry not set: 
AX is handle number 


Function 3DH associates a 16-bit file handle with a file. 
The following values are allowed: 


ACCESS Function 
) file is opened for reading 
1 file is opened for writing 
2 file is opened for both reading and writing. 


DS:DX point to an ASCIZ name of the file to be opened. 
The read/write pointer is set at the first byte of the file 


and the record size of the file is 1 byte. The returned 
file handle must be used for subsequent I/O to the file. 
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Error returns: 


AX 
12 = invalid access 
The access specified in AL was not in the 
range 9:2. 
2 = file not found 


The path specified was invalid or not found. 

5 = access denied 
The user attempted to open a directory or 
volume-id, or open a read-only file for 
writing. 


4 = too many open files 
There were no free handles available in the 
current process or the internal system tables 
were full. 

Example 

lds dx, name 

mov ah, 3DH 

mov - al, access 

int 21H 


; ax has error or file handle 
; If successful open 
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Close a File Handle (Function 3EH) 


x Bay we Call 
x owt ee | AH = 3EH 
cx | cH | c& | Bx 
ox [| oF | mo |” File handle 
fl 
oo ee 
AX 
a 6 = invalid handle 


FLAGSH F RAGM | Carry not set: 
No error 


In BX is passed a file handle (like that returned by 
Functions 3DH, 3CH, or 45H), Function 3EH closes the 
associated file. Internal buffers are flushed. 


Error return: 


AX 
6 = invalid handle 
The handle passed in BX was not currently 
open. 
Example 
mov bx, handle 
mov ah, 3EH 


int 21H 
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Read From File/Device (Function 3FH) 


Call 
AH = 3FH 
DS:DX 
Pointer to buffer 
CX 
Bytes to read 
BX 


File handle 


Return 
Carry set: 
AX 


as ee 

aa ae Number of bytes read 
an eel 6 = invalid handle 
fe 


5 = error set: 
Carry not set: 
AX = number of bytes read 


Function 3FH transfers count bytes from a file into a buffer 
location. It is not guaranteed that all count bytes will be 
read; for example, reading from the keyboard will read at 
most one line of text. If the returned value is zero, then 
the program has tried to read from the end of file. 


All I/O is done using normalized pointers; no segment 
wraparound will occur. 


Error returns: 


AX 
6 = invalid handle 
The handle passed in BX was not currently 
open. 
5 = access denied 
The handle passed in BX was opened in a mode 
that did not allow reading. 
Example 
lds dx, buf 
mov cx, count 
mov bx, handle 
mov ah, 3FH 
int 21H 


; ax has number of bytes read 
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Write to a File or Device (Function 4@H) 


AX Call 
BX: AH = 46H 
Cx: DS:DX 
Dx: Pointer to buffer 
Cx 
Bytes to write 
BX 


File handle 


Return 
Carry set: 
AX 
Number of bytes written 
6 = invalid handle 
5 = access denied 
Carry not set: 
AX = number of bytes written 


Function 49H transfers count bytes from a buffer into a 
file. It should be regarded as an error if the number of 
bytes written is not the same as the number requested. 


The write system call with a count of zero (CX = 6) will set 
the file size to the current position. Allocation units are 
allocated or released as required. 


All 1/0 is done using normalized pointers; no segment 
wraparound will occur. 


Error returns: 


AX 
6 = invalid handle 
The handle passed in BX was not currently 
open. 
5 = access denied 
The handle was not opened in a mode that 
allowed writing. 
Example 
lds dx, buf 
mov cx, count 
mov bx, handle 
mov ah, 4@H 
int 21H 


;ax has number of bytes written 
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Delete a Directory Entry (Function 41H) 


Call 
AH = 41H 
DS:DX 
Pointer to pathname 


2 = file not found 
5 = access denied 
Carry not set: 


Function 41H removes a directory entry associated with a 
filename. 


Error returns: 
AX 
2 = file not found 
The path specified was invalid or not found. 


v 


5 = access denied 
The path specified was a directory or 
read-only. 
Example 
lds dx, name 
mov ah, 41H 


int 21H 
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Move File Pointer (Function 42H) 


Call 
AH = 42H 
CX:DX 


RRR 


AL 


‘BX 


Return 

Carry set: 

AX 
6 
1 


Distance to move, in bytes 


Method of moving: 
(see text) 


File handle 


invalid handle 
invalid function 


Carry not set: 
DX:AX = new pointer location 


Function 42H moves the read/write 
of the following methods: 


Method Function 


G The pointer is moved to 
beginning of the file. 


1 The pointer is moved to 


plus offset. 
2 The pointer is moved to 
offset. 


Offset should be regarded as a 
occupying the most significant 16 


Error returns: 


pointer according to one 


offset bytes from the 
the current location 


the end of file plus 


32-bit integer with CX 
bits. 


BX was not currently 


The function passed in AL was not in the range 


AX 
6 = invalid handle 
_ The handle passed in 
open. 
1 = invalid function 
0:2. 
Example 
mov dx, offsetlow 
mov ex, offsethigh 
mov al, method 
mov bx, handle 
mov ah, 42H 
int 21H 


; dxsax has the new location of the pointer 
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Change Attributes (Function 43H) 


Call 
= AH = 43H 
pas DS:DX 
ne Pointer to pathname 


CX (if AL = @1) 
Attribute to be set 
AL 
Function 
01 Set to CX 
@@ Return in CX 


Carry set: 


= path not found 
5 = access denied 

= invalid function 
Carry not set: 

CX attributes (if AL = @@) 


Given an ASCIZ name, Function 42H will set/get the 
attributes of the file to those given in CX. 


A function code is passed in AL: 
AL Function 


@ Return the attributes of the file in CX. 
1 Set the attributes of the file to those in Cx. 


Error returns: 


AX 
3 = path not found 
The path specified was invalid. 
5 = access denied 
The attributes specified in CX contained one 
that could not be change (directory, volume 
ID). 3 
1 = invalid function 
The function passed in AL was not in the range 
G31. 
Example 
lds dx, name 
mov cx, attribute 
mov al, func 
int ah, 43H 


int 21H 
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I/O Control for Devices (Function 44H) 


. Call 
ia AH = 44H 
me BX 
px. Handle 
BL 


ae ae Drive (for calls AL = 4, 5 
a ee 5 @ = default, 1 = A, etc.) 
[sd s«éSE DX 
a a Data or buffer 
Cx 

a ae Bytes to read or write 
AL 

Function code; see text 


Return 
Carry set: 
AX 


invalid handle 
invalid function 
3 = invalid data 

5 = access denied 
Carry not set: 


6 
1 
1 


AL = 27374,5 
AX = Count transferred : 
AL = 6,7 

08 = Not ready 

FF = Ready 


Function 44H sets or gets device information associated with 
an open handle, or sends/receives a control string to a 
device handle or device. 


The following values are allowed for function: 


Request Function 
i] Get device information (returned in DX) 
1 Set device information (as determined by DX) 
2 Read CX number of bytes into DS:DX from device 
control channel. 


3 Write CX number of bytes from DS:DX to device 
control channel. 

4 Same as 2 only drive number in BL 
@=default,A:=1,B:=2,... 

5 Same as 3 only drive number in BL 


@=default,A:=1,B:=2,... 
6 Get input status 
7 Get output status 


This function can be used to get information about device 
channels. Calls can be made on regular files, but only 
calls @,6 and 7 are defined in that case (AL=@,6,7). All 
other calls return an invalid function error. 


SYSTEM CALLS 


I/O Control for Devices 


Calls AL=9 and’ AL=1 


The bits of 


AL=8 and AL=1. 


on a set ca 


15 


ISDEV 


If ISDEV 


EOF 
RAW 


ISCLK 
ISNUL 
ISCOoT 
ISCIN 
SPECL 


CTRL 


CTRL 


NOTE 


If ISDE 
EOF 
Bits 


DX are defined as 


ll. 


14 13 12 11 10 9 8/7 6 


Reserved 


@ in this case) 


1 


End Of File 
this device 
this device 
this device 
this device 
this device 
this device 
this device 


on 
is 
is 
is 
is 
is 
is 
is 


g 
1 
8 
1 
1 
1 
1 
1 


@ if this device can 


strings via calls AL= 


if this device 


1 


follows 
Note that the upper byte MUST be zero 
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for calls 


5 4 


Crom UNH 
Caw AH 


1 if this channel is a device 
@ if this channel is a disk file (Bits 8-15 


input 

in Raw mode 

cooked : 
the clock device 
the null device 
the console output 
the console input 
special 


not do control 
2 and AL=3. 
can process 


control strings via calls AL=2 and 


AL=3. 


that this bit cannot be set. 


Vv 8 


block 
As, 


0-5 are the 
the channel (98 


@ if channel has been written 


number for 


eee) 


device 
1 = Bs, 


Bits 15,8-13,4 are reserved and should not be 


altered 


Calls 2..5:3 


These four calls allow arbitrary control strings to be 


sent or rec 


eived from a device. 


The 


call syntax is 


the same as the read and write calls, except for 4 and 


5, which take a drive number in BL instead of a 


in BX. 


handle 
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An invalid function error is returned if the 
CTRL bit (see above) is @. 


An access denied is returned by calls AL=4,5 if 
the drive number is invalid. 


Calls 6,7: 
These two calls allow the user to check if a file 
handle is ready for input or output. Status of 
handles open to a device is the intended use of these 
calls, but status of a handle open to a disk file is 
allowed, and is defined as follows: 


Input: ; 
Always ready (AL=FF) until EOF reached, then 
always not ready (AL=9) unless current 
position changed via LSEEK. 

Output: 


Always ready (even if disk full). 


IMPORTANT 


The status is defined at the 
time the system is CALLED. On 
future versions, by the time 


control is returned to the 7 
user from the system, the 
status returned may NOT 


correctly reflect the true 
current state of the device or 
file. 


Error returns; 


AX 
6 = invalid handle 
The handle passed in BX was not currently 
open. 
1 = invalid function 
The function passed in AL was not in the range 
0:7. 
13 = invalid data 
5 = access denied (calls AL=4..7) 


SYSTEM CALLS 


Example 


mov 


(or mov 


(or 


se me SO NO 


mov 
lds 
mov 
mov 
mov 
int 


bx, 
bl, 


ax, 
dx, 
CX, 
ah, 
al, 
21H 


I/O Control for Devices 


Handle 
drive 


Data 
buf 
count 
44H 
func 
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for calls AL=4,5 
O=default,A:=l...) 


and 
for calls AL=2,3,4,5) 


For calls AL=2,3,4,5 AX is the number of bytes 
transferred (same aS READ and WRITE). 

For calls AL=6,7 AL is status returned, AL=9 if 
status is not ready, AL=@FFH otherwise. 
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Duplivst2 a Pile "se1%e (Function 45H) 

Call 

AH = 45H 

Bx 

File handle 
on SP 
a Se Carry set? 
ee ee 
Pe 6 = invalid handle 
4 = too many open files 

| FLAGSH F LAGS. | 

Carry not set: 
AX = new file handle 
ae ee 
Pi Oe 


Function 45H takes an already opened file handle and returns 


a new handle that refers to the same file at the same 
position. 


Error returns: : 
AX 
6 = invalid handle 


The handle passed in BX was not currently 
open. 


4 = too many open files 
There were no free handles available in the 
current process or the internal system tables 
were full. 

Example 

mov bx, fh 

mov ah, 45H 

int 21H 


; ax has the returned handle 
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Force a Duplicate of a Handle (Function 46H) 


Existing file handle 


New file handle 


Return 
Carry set: 
AX 
6 invalid handle 
4 too many open files 
Carry not set: 
No error 


Function 46H takes an already opened file handle and returns 
a new handle that refers to the same file at the same 
position. If there was already a file open on handle Cx, it 
is closed first. 


Error returns: 


AX : 
6 = invalid handle 2) 
The handle passed in BX was not currently e. 
open. 
4 = too many open files 


There were no free handles available in the 
current process or the internal system tables 
were full. , 


Example 
mov bx, fh 
mov cx, newfh 
mov ah, 46H 


int 21H 


SYSTEM CALLS Return Text of Current Directory Page 1-127. 


Return Text of Current Directory (Function 47H) 


Call 
AH = 47H 
DS:SI 
Pointer to 64-byte memory area 
DL 
Drive number 


Return 
Carry set: 
AX 
15 = invalid drive 
Carry not set: 

No error 


Function 47H returns the current directory for a particular 
drive. The directory is root-relative and does not contain 
the drive specifier or leading path separator. The drive 
code passed in DL is @=default, 1=A:, 2=B:, etc. 


Error returns: 
AX 
15 = invalid drive 
The drive specified in DL was invalid. 


Example 
mov ah, 47H 
lds si,area 
mov dl,drive 
int 21H 


ds:si is a pointer to 64 byte area that 


; 
; contains drive current directory. 
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Allocate Memory’ (Function 48H) 


Size of memory to be allocated 


Return 
Carry set: 
AX 
8 
7 
BX 
Maximum size that could be allocated 
Carry not set: 
AX:@ 
Pointer to the allocated memory 


not enough memory 
arena trashed 


Function 48H returns a pointer to a free block of memory 
that has the requested size in paragraphs. 


Error return: 
AX 
8 = not enough memory 
The largest available free block is smaller 
than that requested or there is no free block. 


i? 
" 


arena trashed 
The internal consistency of the memory arena 
has been destroyed. This is due to a user 
program changing memory that does not belong 
to it. 
Example 

mov bx,size 

mov ah,48H 

int 21H 


; ax:@ is pointer to allocated memory 
; if alloc fails, bx is the largest block available 


SYSTEM CALLS 


Free 


OX: 


Free Allocated Memory 


Allocated’ Memory (Function 49H) 


Segment address of memory 
area to be freed 


Return 
Carry set: 
AX 
9 = invalid block 
“7 = arena trashed 
Carry not set: 

No error 
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Function 49H returns a piece of memory to the system pool 
that was allocated by Function Request 49H. 


Error return: 


AX 
9 = invalid block 
7 = arena trashed 
has 
to it. 
Example 
mov es ,block 
mov ah,49H 


The block passed in ES is not one allocated 
via Function Request 49H. 


The internal consistency of the 


program changing memory that does 


int 21H 


bs 


memory arena 


destroyed. This is due to a user 


not belong 
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Modify Allocated Memory Blocks (Function 4AH) 


Segment address of memory area 
BX 
Requested memory area size 


Return 

Carry set: 

AX 

invalid block 
arena trashed 


9 
7 
8 not enough memory 


BX 

Maximum size possible 
Carry not set: 

No error 


Function 4AH will attempt to grow/shrink an allocated block 
of memory. 


Error return: 
AX 
9 = invalid block 7 
The block passed in ES is not one allocated 
via this function. 
arena trashed 
The internal consistency of the memory arena 
has been destroyed. This is due to a user 
program changing memory that does not belong 
to it. 
8 = not enough memory 
There was not enough free memory after the 
specified block to satisfy the grow request. 


~ 
i) 


Example 
mov es,block 
mov bx ,newsize 
mov ah, 4AH 
int 21H 


; if setblock fails for growing, BX will have the 
; maximum size possible 
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Load and Execute a Program (Function 4BH) 


x Fant colt 
x Fey a | THe 
= ae Point hname 
ox EF ae ay er to pathname 
aa ae Pointer to parameter block 
as AL 
ma ee @@ = Load and execute program 
Bea ae 93 = Load program 
ea SS | 
Return 
Carry set: 
a ae AX 
2 ae 1 = invalid function 
ee 19 = bad environment 
Pe 11 = bad format 
8 = not enough memory 


2 = file not found 
Carry not set: 
No error 


This function allows a program to load another program 
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into 


memory and (default) begin execution of it. DS:DX points to 
the ASCIZ name of the file to be loaded. ES:BX points -to a 


parameter block for the load. 


A function code is passed in AL: 


AL Function 

@ Load and execute the program. A program header is 
established for the program and the terminate and 
CONTROL-C addresses are set to the instruction after 
the EXEC system call. 

3 


Load (do not create) the program header, and do 
not begin execution. This is useful in loading 
program overlays. 
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For each value of AL, the block has the following 
format: 


AL = @ -> load/execute program 


WORD segment address of 
environment. 

DWORD pointer to command 
line at 80H 

DWORD pointer to default 
FCB to be passed at 5CH 
DWORD pointer to default 
FCB to be passed at 6CH 


AL = 3 -> load overlay 


mw WORD segment address where 
§ file will be loaded. 
WORD relocation factor to 
be applied to the image. 


Note that all open files of a process are duplicated in the 
child process after an EXEC. This is extremely powerful; 
the parent process has control over the meanings of stdin, 
stdout, stderr, stdaux and stdprn. The parent could, for 
example, write a series of records to a file, open the file 
as standard input, open a listing file as standard output 
and then EXEC a sort program that takes its input from stdin 
and writes to stdout. 


Also inherited (or passed from the parent) is an 
"environment." This is a block of text strings (less than 
32K bytes total) that convey various configurations 
parameters. The format of the environment is as follows: 
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a, : (paragraph boundary) 


BYTE ASCIZ string 1 
BYTE ASCIZ string 2 


BYTE ASCIZ string n 
BYTE of zero 


Typically the environment strings have the form: 


parameter=value 


For example, COMMAND.COM might pass its execution search 
path as; , 


PATH=A:\BIN;B:\BASIC\LIB 


A zero value of the environment address causes the child 
process to inherit the parent's environment unchanged. 


oy Error returns: 
< AX 

1 = invalid function 
The function passed in AL was not @, 1 or 3. 

18 = bad environment 
The environment was larger than 32Kb. 

11 = bad format 
The file pointed to by DS:DX was an EXE format 
file and contained information that was 
internally inconsistent. 

8 = not enough memory 
There was not enough memory for the process to 
be created. 

2 = file not found 

The path specified was invalid or. not found. 


‘Example 
lds dx, name 
les bx, blk 
mov ah, 4BH 
mov al, func 


int 21H 
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Terminate a Process (Function 4CH) 


Return code 


Return 
None 


Function 4CH terminates the current process and transfers 
control to the invoking process. In addition, a return code 
may be sent. All files open at the time are closed. 


This method is preferred over all others (Interrupt 20H, JMP 
8) and has the advantage that CS: 1 does not have to point to 
the Program Header Prefix. 


Error returns: 


None. 
Example 
mov al, code 
mov ah, 4CH 


int 21H 
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Retrieve the Return Code of a Child (Function 4DH) 


x Ba] «| Call 

om | oo | m | . AH = 4DH 
cox | cH | a |. 

ox | on | om |, 

. Return 
ees ee 
a ee 
et Sere 
| FLAGSH | FLAGS. | 
|S 
a 
a 
LS 


Function 4DH returns the Exit code specified by a child 
process. It returns this Exit code only once. The low byte 
of this code is that sent by the Exit routine. The high 
byte is one of the following: 


- Terminate/abort 

- CONTROL-C 

- Hard error 

- Terminate and stay resident 


WNHEe& 


Error returns: 
None. 


Example 
mov ah, 4DH 


| int 21H 
| ; ax has the exit code 
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Find Match File’ (Function 45H) 


Call 
AH = 4EH 
DS:DX 
Pointer to pathname 
CX 
Search attributes 


BRE ® 


Return 
Carry set: 
AX 
2 = file not found 
18 = no more files 
Carry not set: 
No error 


Function 4EH takes a pathname with wild-card characters in 
the last component (passed in DS:DX), a set of attributes 
(passed in CX) and attempts to find all files that match the 
pathname and have a subset of the required attributes. A 
datablock at the current DMA is written that contains 
information in the following form: 


DUP (?); Reserved* 


find_buf reserved DB 21 

find buf attr _ DB ? ; attribute found 
find buf time DW ? 3; time 

find buf date DW ? }; date 

find buf size 1 DW ? ; low(size) 

find buf size h DW ? ; high(size) 

find buf pname DB 13 DUP (?) ; packed name 


find buf ENDS 
*Reserved for MS-DOS use on subsequent find_nexts 


To obtain the subsequent matches of the pathname, see the 
description of Function 4FH. 


Error returns: 


AX 
2 = file not found 
The path specified in DS:DX was an _ invalid 
path. 
18 = no more files 
There were no files matching this 


specification. 


7) 
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sw, Example 


mov ah, 4EH 
lds dx, pathname 
mov cx, attr 
int 21H 


; dma address has datablock 
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Step Through a Directory Matching Files (Function 4FH) 


Call 
AH = 4FH 


eee], eee 
ee ol) ees ee 
a 
18 = no more files 
aC ae Carry not set: 

No error 


Function 4FH finds the next matching entry in a directory. 
The current DMA address must point at a block returned by 
Function 4EH (see Function 4EH). 


Error returns: 
AX 
18 = no more files 
There are no more files matching this pattern. 


Example 


dma points at area returned by Function 4FH 
mov ah, 4FH 
int 21H 

; next entry is at dma 


=e 
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{ } Return Current Setting of verify After Write Eras 
(Function 54H) 


Sas 

a ae 

caer ca Current verify flag value 
a a | 

a Sse 


The current value of the verify flag is returned in AL. 


Error returns: 


( : None. 
Example 
mov ah ,54H 
int 21H 


; al is the current verify flag value 
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Move a Directory Entry (Function 56H) 


Call 

AH = 56H 

DS:DX 
Pointer to pathname of 
existing file 

ES:DI 
Pointer to new pathname 


Return 
Carry set: 
AX 
2 = file not found 
17 = not same device 
5 = access denied 
Carry not sets 
No error 


Function 56H attempts to rename a file into another path. 
The paths must be on the same device. 


Error returns: . 

AX : a 
2 = file not found 
A The file name specifed by DS:DX was not found. 


17 = not same device 
The source and destination are on different 
drives. 

5 = access denied 
The path specified in DS:DX was a directory or 
the file specified by ES:DI exists or the 
destination directory entry could not be 
created. 

Example 

lds dx, source 

les di, dest 

mov ah, 56H 


int 21H 5 
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Get/Set Date/Time of File (Function 57H) 


AH = 57H 


098 = get date and time 


a @1 = set date and time 

ae ae BX 

File handle 

fe ie 8) CX (if AL = @1) 

ae aes Time to be set 

——e oy ee 
ate to be set 

Trias: Fao | : 

FS Return 

ee | Carry set: 

fa ee AX 

FS 


1 = invalid function 
6 = invalid handle 
Carry not set: 
CX/DX set if function 9 
Function 57H returns or sets the last-write time for a 
handle. These times are not recorded until the file is 
closed. 
A function code is passed in AL: 
AL Function 


@ Return the time/date of the handle in CxX/Dx 
1 Set the time/date of the handle to CX/Dx 


Error returns: 


AX 
1 = invalid function 
The function passed in AL was not in the range 
O31. 
6 = invalid handle 
The handle passed in BX was not currently 
open. 
Example 


mov ah, 57H 
mov al, func 
mov bx, handle 
; if al = 1 then then next two are mandatory 


; if al = @ then cx/dx has the last write time/date 
; for the handle. 
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1.8 MACRO DEFINITIONS FOR MS-DOS SYSTEM CALL EXAMPLES 


NOTE 


These macro definitions apply 
to system call examples @@H 
through 57H. 


exlist 


’ 
KRkKKKKKKKKKKKKKKKKKK 


Interrupts 
kkkkRaRKKKKKRKKKKKKKKK 


me we Ne WO 


| ;ABS_DISK_READ 
abs _disk_read macro disk,buffer,num_sectors,first sector 


mov al,disk 

mov bx,offset buffer 

mov cx,num_ sectors 

mov dx,first_sector 

int 37 ;interrupt 37 
popft 

endm 


; 
;ABS DISK WRITE 
abs disk write macro disk,buffer,num_sectors,first_sector 


mov al,disk 
mov bx,offset buffer 
mov cx,num_ sectors 
mov dx,first_sector 
int 38 ;interrupt 38 
popf 
endm 
t 
stay resident macro last_instruc ;STAY RESIDENT 
= mov dx,offset last instruc 
inc dx = 
int 39 zinterrupt 39 
endm - 


RKRKKKEKKKKKKRKKKKKKEK 


; 
; 
; Functions 
gRRRKRKRKKEKEKEKKEKKKKEK 
; 

xr 


ead kbd and echo macro ;READ KBD AND ECHO 
~ ~~ mov ah,l sfunction 1 ~— 
int 33 
endm 
; 
display char macro. character ;DISPLAY CHAR 


mov dl,character 


| 
i 
| 
| 
i 


SYSTEM CALLS 


mov 
int 
endm 
7 
aux input macro 
- mov 
int 
endm 
; 
aux output macro 
~ mov 
int 
endm 
;7page 
print char macro 
- mov 
mov 
int 
endm 


Get/Set Date/Time 


ah,2 
33 


character 
dl,character 
ah,5 

33 


; 
dir console io macro switch 


mov 
mov 
int 
endm 


dl,switch 
ah,6 


33 


Hi a 
dir console input macro 


mov 
int 
endm 

; 

read_kbd macro 
mov 
int 
endm 


c 

display macro 
mov 
mov 
int 
endm 


Ul 
get string macro 
~ mov 
mov 
mov 
int 
endm 


ah,7 
33 


ah,8 
33 


string 

dx,offset string 
ah,9 

33 


limit,string 
string,limit 
dx,offset string 
ah,1@ 

33 


if 
check_kbd_status macro 


ah,1l 
33 


a 
flush_and_read_kbd macro switch 
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;function 2 


;AUX_INPUT 
;function 3 


;AUX_OUTPUT 
;function 4 


;PRINT_ CHAR 


sfunction 5 


;DIR_CONSOLE_I0 


;function 6 


;DIR_CONSOLE INPUT 
;function 7 


; READ_KBD 
;function 8 


;DISPLAY 


sfunction 9 


;GET_STRING 


;function 19 


;CHECK_ KBD STATUS 
sfunction 11 


;FLUSH_AND_READ_KBD 
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mov 
mov 
int 
endm 
; 
reset disk macro 
_ mov 
int 
endm 
77page 
select disk macro 
~ mov 
mov 
int 
endm 


macro 
mov 
mov 
int 
endm 


macro 
mov 
mov 
int 
endm 


’ 
search first macro 
~ mov 
mov 
int 
endm 
; 
search next macro 
~ mov 
mov 
int 
endm 


macro 
mov 
mov 
int 
endm 


; 
delete 


, 

read seq macro 

~ mov 

mov 

int 

endm 

; 

write seq macro 
mov 
mov 
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al,switch 
ah,12 


disk 
d1l,disk[-65] 
ah,14 

33 


fcb 
dx,offset 
ah,15 

33 


fcb 


fcb 
dx,offset 
ah,16 

33 


f£cb 


f£cb 
dx,offset 
ah,17 

33 


fcb 


Ecb 
dx,offset 
ah,18 

33 


fcb 


fcb 
dx,offset 
ah,19 

33 


fcb 


fcb 
dx,offset 
ah,29 

33 


fcb 


fcb 
dx,offset 
ah,21 


£cb 


;function 12 


;RESET DISK 
;function 13 


;SELECT DISK 


;function 14 


7 OPEN 


sfunction 15 


;CLOSE 


;function 16 


;SEARCH FIRST 


;Function 17 


; SEARCH NEXT 


;function 18 


;DELETE 


sfunction 19 


;READ_ SEQ 


;function 29 


;WRITE_SEQ 


;function 21 
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SYSTEM CALLS 


c 
create 


’ 
rename 


int 
endm 


macro 
mov 
mov 
int 
endm 


macro 
mov 
mov 
int 
endm 


a 
current disk macro 


? 
set_dta 


mov 
int 
endm 


macro 
mov 
mov 
int 
endm 


’ “ 
alloc_table macro 


’ 
read_ran 


e 
write ran 


’ 
set_ relative record 


mov 
int 
endm 


macro 
mov 
mov 
int 
endm 


macro 
mov 
mov 
int 
endm 


macro 
mov 
mov 
int 
endm 


mov 
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33 


fcb 

dx,offset: fcb 
ah,22 

33 


fcb, newname 
dx offset fcb 
ah,23 

33 


buffer 

dx,offset buffer 
ah,26 

33 


ah,27 
33 


fcb 

dx,offset fcb 
ah,33 

33 


E£cb 

dx,offset fcb 
ah, 34 

33 


fcb 

dx,offset fcb 
ah,35 

33 


macro fcb 
dx,offset fcb 
ah,36 


;CREATE 


;function 22 


; RENAME 


;function 23 


;CURRENT_ DISK 
sfunction 25 


;SET_DTA 


;function 26 


;ALLOC TABLE 
;function 27 


;READ_RAN 


sfunction 33 


;WRITE_RAN 


;function 34 


;FILE_SIZE 


sfunction 35 


;SET_RELATIVE_RECORD 


sfunction 36 
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set_vector macro interrupt,seg_ addr,off_addr ;SET_VECTOR 


push ds 
mov ‘“ax,seg addr 
Mov ds,ax 
mov dx,off addr 
mov al,interrupt 
mov ah,37 ;function 37 
int 33 
endm 
a 
create prog seg macro seg_addr ;CREATE PROG SEG 
mov dx,seg addr 
mov ah,38 sfunction 38 
int 33 
endm 


’ 
ran_block_read macro fcb,count,rec_size ;RAN_BLOCK_ READ 


mov dx,offset fcb 

mov ex,count 

mov word ptr fcb[14],rec size 

mov ah ,39 ;function 39 
int 33 

endm 


’ 
ran_block write macro fcb,count,rec_ size ;RAN_BLOCK WRITE 


mov dx,offset fcb 
mov ecx,count 
mov word ptr fcb[14],rec_size 
mov ah,4@ ;function 49 
int 33 
endm 

, 

parse macro filename,fcb 7 PARSE 
mov si,offset filename 
mov di,offset fcb 
push es 
push ds 
pop es 
mov al,15 
mov ah,41 ;function 41 
int 33 
pop es 
endm 

v 

get date macro 7;GET_ DATE 

= mov ah,42 ;function 42 

int 33 
endm 

*7page 

set date macro year ,month,day ;SET_ DATE 
mov cx,year 
mov dh,month 
mov dl,day 
mov ah, 43 sfunction 43 


int 33 
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endm — 
f 
get_time macro ;GET_TIME 
mov ah,44 sfunction 44 
int 33 
endm 
: , 
;SET_TIME 
set time macro hour ,minutes,seconds ,hundredths 
mov ch,hour 
mov cl,minutes 
mov dh,seconds 
mov dl,hundredths 
mov ah,45 sfunction 45 
int 33 
endm 
, 
verify macro switch ; VERIFY 
mov al,switch 
mov ah, 46 sfunction 46 
int 33 
endm 


; 
gRRKKKKREREEEKEREKEE 

; General 

gRAKKKEREKEKREREREKEEE 

; : : 

move string macro source,destination,num_ bytes 
;MOVE_STRING 


push es 
mov ax,ds 
mov es,ax 
assume es:data 
mov si,offset source 
mov di,offset destination 
mov cx,num_bytes 
rep movs - es:destination,source 
assume es:nothing 
pop es 
endm 
; 
t 
convert macro value,base,destination ; CONVERT 
local table,start 
jmp start 
table db "9123456789ABCDEF" 
start: mov al,value 
XOX ah,ah 
XOL bx ,bx 
div base 
mov bl,al 
mov al,cs:table[bx] 
mov destination,al 
mov bl,ah 


mov al,cs:table[bx] 
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mov - destination[1] ,al 
endm 
7;page 
convert to binary macro. string,number,value 
=e ;CONVERT TO BINARY 


local ten,start,calc,mult,no mult 
jmp start 
ten db 108 
start: mov value,@ 
xor CX ,CXx 
mov cl,number 
xOr si,si 
calc: xor ax,ax 
mov al,string[si] 
sub al,48 
cmp Cx ,2 
jl no mult 
push cx 
dec cx 
mult: mul essten 
loop mult 
pop cx 
no mult: add value,ax 
inc si 
loop calc 
endm 


v 
convert date macro dir entry 


mov dx,word ptr dir_entry[25] 
mov c1,5 

shr dl,cl 

mov dh,dir_entry[25] 

and dh,lfh 

xor cx,cx 

mov cl,dir_entry[26] 

shr cl,l 

add cx,1980 


endm 


=e 


SYSTEM CALLS 


t 


1.9 EXTENDED EXAMPLE OF MS-DOS SYSTEM CALLS 


title DISK DUMP 
Zero 

‘disk B 
sectors per read 


INCLUDE B:CALLS.EQU 


; 

subttl DATA SEGMENT 
page + 

data 


; 
input buffer 
output buffer 


start prompt 
sectors prompt 
continue_prompt 
header 

end_ string 


crlf 

table 

; 

ten 

sixteen 

; 

start sector 
sector num 
sector number 
sectors to dump 
sectors read 


a 

buffer 
max_length 
current_length 
digits 


’ 

data 

; 

subttl STACK SEGMENT 


page + 
stack 


stack_top 
stack 


; 
subttl MACROS 
page + 


f 
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equ 9g 
equ l 
equ. 9 
equ 13 
equ) 32 
equ 46 
equ 126 
segment 
db 9 dup(512 dup(?)) 
db 77 dup (" Wy) 
db @DH,@AH,"S" 
db "Start at sector: $" 
ab "Number of sectors: s§" 
db "RETURN to continue $" 
db “Relative sector §$" 
db ODH,@AH,@AH,@7H,"ALL DONES" 
;DELETE THIS 

db @DH,@AH,"S" 
db "@123456789ABCDEFS" 
db 190 
db 16 
dw 1 

label byte 
dw @ 
dw sectors_per_read 
dw @ 

label byte 
db @ 
db @ 
db 5 dup(?) 
ends 
segment stack 
dw 188 dup(?) 
label word 
ends 
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INCLUDE B:CALLS.MAC 


7;BLANK LINE 
blank_line 


print_it: 


; 
subttl ADDRESSABILITY 


page + 
code 


starts: 


° 
e 


subttl PROCEDURES 
page + 


; 

; PROCEDURES 
; READ DISK 
read_ disk 


get_sector: 


done: 

read disk 
;CLEAR_LINE 
clear_line 


move blank: 


macro 
local 
push 
call 
mov 
display 
loop 
pop 
endm 


segment 
assume 
mov 
mov 

mov 

mov 

mov 


jmp 


proc; 
cmp 
jle 
mov 
mov 
mov 
mov 
cmp 


. jle 


mov 
push 
int 
popf 
pop 
sub 
add 
mov 
XOX 
ret 
endp 


proc; 
push 
mov 
XOX 
mov 
inc 
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clear line 
cx,number 
output_ buffer 
print_ It 

cx 


cs:code,ds:data,ss:stack 
ax ,data 

ds,ax 

ax,Stack 

SS,ax 

sp,offset stack top 


main procedure 


sectors to _dump,zero 
done 

bx,offset input buffer 
dx,start sector | 
al,disk b 

cx,sectors per read 
cx,sectors to dump 
get_sector 
cx,sectors to dump 
cx 

disk_read 


cx 
sectors to_dump,cx 
start sector, cx 
sectors _read,cx 
si,si 


cx 
cx,77 

bx,bx 

Output buffer[bx],' ' 
bx > 
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t j loop move blank 
. pop cx 
ret 

clear_line endp 

v 

';PUT_BLANK 

put_blank ~ proc; 
mov output _buffer[di]," " 
inc di 
ret 

put_blank endp 

; 

; 

setup proc; 


display start prompt 

get string 4,buffer 
display ocrlf 
convert _to binary digits, 
current length,start sector 
mov ax,start sector 
mov sector number,ax 
display sectors prompt 
get_string 4,buffer 
convert _to_binary digits, 
current length,sectors to_dump 


( r ret 
: setup endp 
a 
;CONVERT LINE 
convert_line : proc; 
push cx 
mov di,9 
mov cx,16 
convert_it: convert input buffer[si],sixteen, 
output_buffer [di] 
inc si 
add di,2 
call put_blank 
loop convert_it 
sub si,16 
mov cx,16 
add di,4 
‘display ascii: mov output buffer [di] ,period 
cmp input_buffer[si],blank 
ji non_printable 
cmp input_buffer[si],tilde 
jg non printable 
printable: mov dl,input_buffer [si] 
mov output_buffer[di] ,dl 
non_printable: ine si 
inc di 
loop display ascii 
pop cx 
ret 


convert line endp 


SYSTEM CALLS 


f 


;DISPLAY SCREEN 
display screen 


’ 
;I WANT length header 


sminus 1 in cx 


move header: 


me 


dump_it: 


display screen 


END PROCEDURES 
subttl MAIN PROCEDURE 
page + 

main procedure: 

check done: 


me te NO 


display it: 


all _ done: 


code 
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proc; 
push cx 
call clear line 
mov cx,17 
dec cx 
xOr di,di 
mov al,header [di] 
mov output buffer [di] ,al 
inc di ~ 
loop move header ;FIX THIS! 
convert sector num[1],sixteen, 
output buffer [di] 
add = di,2 
convert sector num,sixteen, 
output_buffer [di] 
display output buffer 
blank line 2 ie 
mov cx,16 
call clear line 
call convert line 
display output_buffer 
loop dump_it 
blank line 3 
display continue prompt 


get_char_no_ echo 
display crlft 


pop cx 
ret 

endp 

call setup 

cmp sectors to dump,zero 
jng all done ~— 

call read disk 

mov ex,sectors read 
call display screen 
call display screen 

inc sector number 

loop display it 

jmp check_done 

display end_ string 
get_char_no echo 

ends 


end start 


CHAPTER 2 


MS-DOS 2.8 DEVICE DRIVERS 


2.1 WHAT IS A DEVICE DRIVER? 


A device driver is a binary file with all of the code in it 
to manipulate the hardware and provide a consistent 
interface to MS-DOS. In addition, it has a special header 
at the beginning that identifies it as a device, defines the 
strategy and interrupt entry points, and describes various 
attributes of the device. 


NOTE 


For device drivers, the file 
must not use the ORG 16@@H 
(like .COM files). Because it 
does not use the Program 
Segment Prefix, the device 
driver is simply loaded; 
therefore, the file must have 
an origin of zero (ORG @ or no 
ORG statement). 


There are two kinds of device drivers. 
1. Character device drivers 


2. Block device drivers 


Character devices are designed to perform serial character 
I/O like CON, AUX, and PRN. These devices are named (i.e., 
CON, AUX, CLOCK, etc.), and users may open channels (handles 
or FCBs) to do I/O to them. 


Block devices are the "disk drives" on the system. They can 
perform random 1/0 in pieces called blocks (usually the 
physical sector size). These devices are not named as the 
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character devices are, and therefore cannot be opened 
directly. Instead they are identified via the drive letters 
(A:, Bz, Cz, etc.). 


Block devices also have units. A single driver may be 
responsible for one or more disk drives. For example, block 
device driver ALPHA may be responsible for drives A:,B:,C: 
and Ds. This means that it has four units (0-3) defined 
and, therefore, takes up four drive letters. The position 
of the driver in the list of all drivers determines which 
units correspond to which driver letters. If driver ALPHA 
is the first block driver in the device list, and it defines 
4 units (9-3), then they will be A:,B:,C: and D:. If BETA 
is the second block driver and defines three units (@-2), 
then they will be E:,F: and G:, and so on. MS-DOS 2.8 is 
not limited to 16 block device units, as previous versions 
were. The theoretical limit is 63 (26 - 1), but it should 
be noted that after 26 the drive letters are unconventional 
(such as ], \, and “*). 


NOTE 
Character devices cannot 


define multiple units because 
they have only one name. 
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2.2 DEVICE HEADERS 


A device header is required at the beginning of a device 
driver. A device header looks like this: 


DWORD pointer to next device 
(Must be set to -1l) 


WORD attributes 
Bit 15 = 1 if char device @ is blk 
if bit 15 is l 


Bit @ = 1 if current sti device 
Bit 1 = 1 if current sto output 
Bit 2 = 1 if current NUL device 
Bit 3 = 1 if current CLOCK dev 
Bit 4 = 1 if special 


Bits 5-12 Reserved; must be set 
to @ 
Bit 14 is the IOCTL bit 
Bit 13 is the NON IBM FORMAT bit 


WORD pointer to device ee 
entry point 


WORD pointer to device interrupt 


entry point 


8-BYTE character device name field 

Character devices set a device name. 
For block devices the first byte is 
the number of units 


Figure 2. Sample Device Header 


Note that the device entry points are words. They must be 
offsets from the same segment number used to point to this 
table. For example, if XXX:YYY points to the start of this 
table, then XXX:strategy and xXxXX:interrupt are the entry 
points. 


2.2.1 Pointer To Next Device Field 


The pointer to the next device header field is a double word 
field (offset followed by segment) that is set by MS-DOS to 
point at the next driver in the system list at the time the 
device driver is loaded. It is important that this field be 
set to -l prior to load (when it is on the disk as a file) 
unless there is more than one device driver in the file. If 
there is more than one driver in the file, the first word of 
the double word pointer should be the offset of the next 
driver's Device Header. 
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NOTE 


If there is more than one 
device driver in the .COM 
file, the last driver in the 
file must have the pointer to 
the next Device Header field 
set to -l. 


2.2.2 Attribute Field 


The attribute field is used to tell the system whether this 
device is a block or character device (bit 15). Most other 
bits are used to give selected character devices certain 
special treatment. (Note that these bits mean nothing on a 
block device). For example, assume that a user has a new 
device driver that he wants to be the standard input and 
output. Besides installing the driver, he must tell MS-Dos 
that he wants his new driver to override the current 
standard input and standard output (the CON device). This 
is accomplished by setting the attributes to the desired 
characteristics, so he would set bits 8 and 1 to 1 (note 
that they are separate!). Similarly, a new CLOCK device 
could be installed by setting that attribute. (Refer to 
Section 2.7, "The CLOCK Device," in this chapter for more 
information.) Although there is a NUL device attribute, the 
NUL device cannot be reassigned. This attribute exists so 
that MS-DOS can determine if the NUL device is being used. 


The NON IBM FORMAT bit applies only to block devices and 
affects the operation of the BUILD BPB (Bios Parameter 
Block) device call. (Refer to Section 2.5.3, "MEDIA CHECK 
and BUILD BPB," for further information on this call). 


The other bit of interest is the 1I0CTL bit, which has 
meaning on character and block devices. This bit tells 
MS-DOS whether the device can handle control strings (via 
the IOCTL system call, Function 44H). 


If a driver cannot process control strings, it should 
initially set this bit to @. This tells MS-DOS to return an 
error if an attempt is made (via Function 44H) to send or 
receive control strings to this device. A device which can 
Process control strings should initialize the IOCTL bit to 
l. For drivers of this type, MS-DOS will make calls to the 
IOCTL INPUT and OUTPUT device functions to send and receive 
IOCTL strings. 


The IOCTL functions allow data to be sent and _ received by 
the device for its own use (for example, to set baud rate, 
stop bits, and form length), instead of passing data over 
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the device channel as does a normal read or write. The 
interpretation of the passed information is up to _ the 
device, but it must not be treated as a normal 1/0 request. 


2.2.3 Strategy And Interrupt Routines 


These two fields are the pointers to the entry points of the 
strategy and interrupt routines. They are word values, so 
they must be in the same segment as the Device Header. 


2.2.4 Name Field 


This is an 8-byte field that contains the name of a 
character device or the number of units of a block device. 
If it is a block device, the number of units can be put in 
the first byte. This is optional, because MS-DOS will fill 
in this location with the value returned by the driver's 
INIT code. Refer to Section 2.4, “Installation of Device 
Drivers" in this chapter for more information. 


2.3 HOW TO CREATE A DEVICE DRIVER 


In order to create a device driver that MS-DOS can install, 
you must write a binary file with a Device Header at the 
beginning of the file. Note that for device drivers, the 
code should not be originated at 190H, but rather at 9. The 
link field (pointer to next Device Header) should be -1l, 
unless there is more than one device driver in the file. 
The attribute field and entry points must be set correctly. 


If it is a character device, the name field should be filled 
in with the name of that character device. The name can be 
any legal 8-character filename. 


MS-DOS always processes installable device drivers before 
handling the default devices, so to install a new CON 
device, simply name the device CON. Remember to set the 
standard input device and standard output device bits in the 
attribute word on a new CON device. The scan of the device 
_ list stops on the first match, so the installable device 
driver takes precedence. 
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NOTE 


Because MS-DOS can install the 
driver anywhere in memory, 
care must be taken in any far 
“Memory references. You should 
not expect that your driver 
will always be loaded in the 
same place every time. 


2.4 INSTALLATION OF DEVICE DRIVERS 


MS-DOS 2.8 allows new device drivers to be installed 
dynamically at boot time. This is accomplished by INIT code 
in the BIOS, which reads and processes the CONFIG.SYS file. 


MS-DOS calls upon the device drivers to perform their 
function in the following manner: 


_MS-DOS makes a far call to strategy entry, and 
passes (in a Request Header) the information 
describing the functions of the device driver. 


This structure allows you to program an interrupt-driven 
device driver. For example, you may want to perform local 
buffering in a printer. 


2.5 REQUEST HEADER 


When MS-DOS calls a device driver to perform a function, it 
passes a Request Header in ES:BX to the strategy entry 
point. This is a fixed length header, followed by data 
pertinent to the operation being performed. Note that it is 
the device driver's responsibility to preserve the machine 
state (for example, save all registers on entry and restore 
them on exit). There is enough room on the stack when 
Strategy or interrupt is called to do about 28 pushes. If 
‘more stack is needed, the driver should set up its own 
Stack. 


The following figure illustrates a Request Header. 
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REQUEST HEADER -> 


BYTE length of record 
Length in bytes of this 
Request Header 


BYTE unit code 
The subunit the operation 
is for (minor device) 
(no meaning on character 
devices) 


BYTE command code 
WORD status 


8 bytes RESERVED 


Figure 3. Request Header 


2.5.1 Unit Code 


The unit code field identifies which unit in your device 
driver the request is for. For example, if your device 
driver has 3 units defined, then the possible values of the 
unit code field would be @, 1, and 2. 


2.5.2 Command Code Field 


The command code field in the Request header can have the 
following values: 


Command Function 
Code 


INIT 

MEDIA CHECK (Block only, 1 noe character) 
BUILD BPB " 

IOCTL INPUT (Only called re pene has IOCTL) 
INPUT (read) 

NON-DESTRUCTIVE INPUT NO WAIT Kenee deve only) 
INPUT STATUS 

INPUT FLUSH " by . 
OUTPUT (write) 

OUTPUT (Write) with verify 

16 OUTPUT STATUS " " 
11 OUTPUT FLUSH . ” " 
12 IOCTL OUTPUT (Only called if device has IOCTL) 


WOMAIVANAUMSPWNEH 
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2.5.3 MEDIA CHECK And BUILD BPB 


MEDIA CHECK and BUILD BPB are used with block devices only. 


MS-DOS calls MEDIA CHECK first for a drive unit. MS-DOS 
passes its current media descriptor byte (refer to the 
section "Media Descriptor Byte" later in this chapter). 
MEDIA CHECK returns one of the following results: 


Media Not Changed - current DPB and media byte are 
OK. 


Media Changed - Current DPB and media are wrong. 
MS-DOS invalidates any buffers for this unit and 
calls the device driver to build the BPB with media 
byte and buffer. 


Not Sure - If there are dirty buffers (buffers with 
changed data, not yet written to disk) for this 
unit, MS-DOS assumes the DPB and media byte are OK 
(media not changed). If nothing is dirty, MS-DOS 
assumes the media has changed. It invalidates any 
buffers for the unit, and calls the device driver 
to build the BPB with media byte and buffer. 


Error - If an error occurs, MS-DOS sets the error 
code accordingly. 


MS-DOS will call BUILD BPB under the following conditions: 
If Media Changed is returned 


If Not Sure is returned, and there are no dirty 
buffers 


The BUILD BPB call also gets a pointer to a one-sector 
buffer. What this buffer contains is determined by the NON 
IBM FORMAT bit in the attribute field. If the bit is zero 
(device is IBM format-compatible), then the buffer contains 
the first sector of the first FAT. The FAT ID byte is’ the 
first byte of this buffer. NOTE: The BPB must be the same, 
as far as location of the FAT is concerned, for all possible 
media because this first FAT sector must be read before the 
actual BPB is returned. If the NON IBM FORMAT bit is. set, 
then the pointer points to one sector of scratch space 
(which may be used for anything). 
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2.5.4 Status Word 
The following figure illustrates the status word in the 


Request Header. 


15 14131211168 9 8 7 6 5 4 3 2 1 86 


RESERVED ERROR CODE (bit 15 on) 


The status word is zero on entry and is set by the driver 
interrupt routine on return, 


Bit 8 is the done bit. When set, it means the operation is 
complete. For MS-DOS 2.0, the driver sets it to 1 when it 
exits. 


Bit 15 is the error bit. If it is set, then the low 8 bits 
indicate the error. The errors are: 


Write protect violation 
Unknown Unit 
Drive not ready 
Unknown command 
CRC error 

Bad drive request structure length 
Seek error 

Unknown media 

Sector not found 

Printer out of paper 

Write fault 

Read Fault 

General failure 


ah 


ADPUODIADULWNHEHA 


Bit 9 is the busy bit, which is set only by status calls. 


For output on character devices: If bit 9 is 1 on 
return, a write request (if made) would wait for 
completion of a current request. If it is 9, there 
is no current request, and a write request (if 
made) would start immediately. 
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For input on character devices with a buffer: If 
bit 9 is 1 on return, a read request (if made) 
would go to the physical device. If it is @ on 
return, then there are characters in the device 
buffer and a read would return quickly. It also 
indicates that something has been typed. MS-DOS 
assumes all character devices have an input 
type-ahead buffer. Devices that do not havea 
type-ahead buffer should always return busy=9 so 
that MS-DOS will not continuously wait for 
something to get into a buffer that does not exist. 


One of the functions defined for each device is INIT. This 
routine is called only once when the device is installed. 
The INIT routine returns a location (DS:DX), which is a 
pointer to the first free byte of memory after the device 
driver (similar to "Keep Process"). This pointer method can 
be used to delete initialization code that is only needed 
once, saving on space. 


Block devices are installed the same way and also return a 
first free byte pointer as described above. Additional 
information is also returned: 


The number of units is returned. This determines 
logical device names. If the current maximum 
logical device letter is F at the time of the 
install call, and the INIT routine returns 4 as the 
number of units, then they will have logical names 
G, H, I and J. This mapping is determined by the 
position of the driver in the device list, and by 
the number of units on the device (stored in the 
first byte of the device name field). 


A pointer to a BPB (BIOS Parameter Block) pointer 
array is also returned. There is one table for 
each unit defined. These blocks will be used _ to 
build an internal DOS data structure for each of 
the units. The pointer passed to the DOS from the 
driver points to an array of n word pointers to 
BPBs, where n is the number of units defined. In 
this way, if all units are the same, all of the 
pointers can point to the same BPB, saving space. 
Note that this array must be protected (below the 
free pointer set by the return) since an internal 
DOS structure will be built starting at the byte 
pointed to by the free pointer. The sector size 
defined must be less than or equal to the maximum 
sector size defined at default BIOS INIT time. If 
it isn't, the install will fail. 


The last thing that INIT of a block device must 
pass back is the media descriptor byte. This byte 
means nothing to MS-DOS, but is passed to devices 


~~ 


MS-DOS 2.98 DEVICE DRIVERS Page 2-11 


so that they know what parameters MS-DOS is 
currently using for a particular drive unit. 


Block devices may take several approaches; they may be dumb 
or smart. A dumb device defines a unit (and therefore an 
internal DOS structure) for. each possible media drive 
combination. For example, unit 9@ = drive @ single side, 
unit 1 = drive @ double side. For this approach, media 
descriptor bytes do not mean anything. A smart device 
allows multiple media per unit. In this case, the BPB table 
returned at INIT must define space large enough to 
accommodate the largest possible media supported. Smart 
drivers will use the media descriptor byte to pass 
information about what media is currently in a unit. 


2.6 FUNCTION CALL PARAMETERS 


All strategy routines are called with ES:BX pointing to the 
Request Header. The interrupt routines get the pointers to 
the Request Header from the queue that the strategy routines 
store them in. The command code in the Request Header tells 
the driver which function to perform. 


NOTE 


All DWORD pointers are stored 
offset first, then segment. 
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2.6.1 INIT 


Command code = @ 
INIT — ES:BX -> 


13-BYTE Request Header 


BYTE # of units 


DWORD break address 


DWORD pointer to BPB array 
(Not set by character devices) 


The number of units, break address, and BPB pointer are set 
by the driver. On entry, the DWORD that is to be set to the 
BPB array (on block devices) points to the character after 
the '=' on the line in CONFIG.SYS that loaded this device. 
This allows drivers to scan the CONFIG.SYS invocation line 
for arguments. 


NOTE 


If there are multiple device 
drivers in a single .COM file, 
the ending address returned by 
the last INIT called will be 
the one MS-DOS uses. It is 
recommended that all of the 
device drivers in a_e single 
~COM file return the _ same 
ending address. 


2.6.2 MEDIA CHECK 


Command Code = 1 


MEDIA CHECK - ES:BX -> 


13-BYTE Request Header 


BYTE media descriptor from DPB 
i BYTE returned 
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In addition to setting the status word, the driver must set 
the return byte to one of the following: 


-~1 Media has ‘been changed 
@ Don't know if media has been changed 
1 Media has not been changed 


If the driver can return -1 or 1 (by having a door-lock or 
other interlock mechanism) MS-DOS performance is enhanced 
because MS-DOS does not need to reread the FAT for each 


directory access. 
2.6.3 BUILD BPB (BIOS Parameter Block) 


Command code = 2 


BUILD BPB - ES:BX -> 


13-BYTE Request Header 
| ByTE media descriptor from DPB 


| DWORD transfer address 

(Points to one sector worth of 
scratch space or first sector 
of FAT depending on the value 
of the NON IBM FORMAT bit) 


| DWORD pointer to BPB 


If the NON IBM FORMAT bit of the device is set, then the 
DWORD transfer address points to a one sector buffer, which 
can be used for any purpose. If the NON IBM FORMAT bit is 
@, then this buffer contains the first sector of the first 
FAT and the driver must not alter this buffer. 


If IBM compatible format is used (NON IBM FORMAT BIT = O), 
then the first sector of the first FAT must be located at 
the same sector on all possible media. This is because the 
FAT sector will be read BEFORE the media is actually 
determined. Use this mode if all you want is to read the 
FAT ID byte. 


In addition to setting status word, the driver must set the 
Pointer to the BPB on return. 
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In order to allow for many different OEMs to read each 
other's disks, the following standard is suggested: The 
information relating to the BPB for a Particular piece of 
media is kept in the boot sector for the media. In 
particular, the format of the boot sector is: 


WORD number of sectors in logical 
image 


The three words at the end (sectors per track, number of 
heads, and number of hidden sectors) are optional. They are 
intended to help the BIOS understand the media. Sectors per 
track may be redundant (could be calculated from total size 
of the disk). Number of heads is useful for supporting 
different multi-head drives which have the same storage 
capacity, but different numbers of surfaces. Number of 
hidden sectors may be used to support drive-partitioning 
schemes. 


wow 


<_— 


WroWw— > 
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2.6.4 Media Descriptor Byte 


The last two digits of the FAT ID byte are called the media 
descriptor byte. Currently, the media descriptor byte has 
been defined for a few media types, including 5-1/4" and 8" 
standard disks. For more information, refer to Section 3.6, 
"MS-DOS Standard Disk Formats." 


Although these media bytes map directly to FAT ID bytes 
(which are constrained to the 8 values F8-FF), media bytes 
can, in general, be any value in the range 6-FF. 
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2.6.5 READ Or WRITE 


Command codes = 3,4,8,9, and 12 


READ or WRITE - ES:BX (Including IOCTL) -> 


13-BYTE Request Header 


BYTE media descriptor from DPB 
DWORD transfer address 
WORD byte/sector count 


WORD starting sector number 
(Ignored on character devices) 


In addition to setting the status word, the driver must set 
the sector count to the actual number of sectors (or bytes) 
transferred. No error check is performed on an IOCTL I/O 
call. The driver must correctly set the return sector 
(byte) count to the actual number of bytes transferred. 


THE FOLLOWING APPLIES TO BLOCK DEVICE DRIVERS: 


Under certain circumstances the BIOS may be asked to perform 
a write operation of 64K bytes, which seems to be a "wrap 
around" of the transfer address in the BIOS I/O packet. 
This request arises due to an optimization added to the 
write code in MS-DOS. It will only manifest on user writes 
that are within a sector size of 64K bytes on files 
"growing" past the current EOF. It is allowable for the 
BIOS to ignore the balance of the write that "wraps around" 
if it so chooses. For example, a write of 1990@H bytes 
worth of sectors with a transfer address of Xxx:l could 
ignore the last two bytes. A user program can never request 
an I/O of more than FFFFH bytes and cannot wrap around (even 
to 9) in the transfer segment. Therefore, in this case, the 
last two bytes can be ignored. 
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2.6.6 NON DESTRUCTIVE READ NO WAIT 


Command code = 5 
NON DESRUCTIVE READ NO WAIT - ES:BX —> 


13-BYTE Request Header 


BYTE read from device 


If the character device returns busy bit = @ (characters in 
buffer), then the next character that would be read is 
returned. This character is not removed from the input 
buffer (hence the term "Non Destructive Read"). Basically, 
this call allows MS-DOS to look ahead one input character. 
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2.6.7 


STATUS 


Command codes = 6 and 19 


STATUS Calls - ES:BX => 


13-BYTE Request Header 


All the driver must do is set the status word and the busy 
bit as follows: 


2.6.8 


For output on character devices: If bit 9 is 1 on 
return, a write request (if made) would wait for 
completion of a current request. If it is 9, there 
is no current request and a write request (if made) 
would start immediately. 


For input on character devices with a buffer: A 
return of 1 means, a read request (if made) would 
go to the physical device. If it is @ on return, 
then there are characters in the devices buffer and 
a read would return quickly. A return of @ also 
indicates that the user has typed something. 
MS-DOS assumes that all character devices have an 
input type-ahead buffer. Devices that do not have 
a type-ahead buffer should always return busy = 9 
so that the DOS will not hang waiting for something 
to get into a buffer which doesn't exist. 


FLUSH 


Command codes = 7 and 1l 


FLUSH Calls - ES:BX -> 


13-BYTE Request Header | 


The FLUSH call tells the driver to flush (terminate) all 


pending 


requests. This call is used to flush the input 


queue on character devices. 
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2.7 THE CLOCK’ DEVICE 


One of the most popular add-on boards is the real time clock 
board. To allow this board to be integrated into the system 
for TIME and DATE, there is a special device (determined by 
the attribute word) called the CLOCK device. The CLOCK 
device defines and performs functions like any other 
character device. Most functions will be: "set done bit, 
reset error bit, return." When a read or write to this 
device occurs, exactly 6 bytes are transferred. The first 
two bytes are a word, which is the count of days’ since 
1-1-86. The third byte is minutes; the fourth, hours; the 
fifth, hundredths of seconds; and the sixth, seconds. 
Reading the CLOCK device gets the date and time; writing to 
it sets the date and time. 
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2.8 EXAMPLE OF DEVICE DRIVERS 
The following examples illustrate a block device driver and 


a character device driver program. 


2.8.1 Block Device Driver 


ge KKKKREKEEKEEKKEEREER DN BLOCK DEVICE #8 XKRKKKKKEREKKKEKR KE 


TITLE 5 1/4" DISK DRIVER FOR SCP DISK-MASTER 


;This driver is intended to drive up to four 5 1/4" drives 
;hooked to the Seattle Computer Products DISK MASTER disk 
;controller. All standard IBM PC formats are supported. 


FALSE EQU 4] 

TRUE EQU NOT FALSE 
;The I/O port address of the DISK MASTER 
DISK EQU OEOH 
7;DISK+@ 

: 1793 Command/Status 
;DISK+1 

; : 1793 Track © 
;DISK+2 

; 1793 Sector 
;DISK+3 

; 1793 Data 
;DISK+4 

: Aux Command/Status 
7;DISK+5 

7 Wait Sync 

;Back side select bit 
BACKBIT EQU @4H 

75 1/4" select bit 

SMALBIT EQU 10H 
;Double Density bit 

DDBIT EQU Q8H 


;Done bit in status register 
DONEBIT EQU Q1H 


;Use table below to select head step speed. 
;Step times for 5" drives 

;are double that shown in the table. 

’ 

7;Step value 1771 1793 


6ms 3ms 
1 6ms 6ms 


me te Ne 
Q 
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; 2. ‘10ms 19ms 
: 3 20ms 15ms 
; 
STPSPD EQU 1 
NUMERR EQU ERROUT~ERRIN 
CR EQU @DH 
LF EQU @AH 
CODE SEGMENT 
ASSUME CS:CODE,DS:NOTHING, ES: NOTHING,SS: NOTHING 
7 ee ee oe ee ee ee ee oe ce ee ee ee oe em re ee es ce ee ee ee ee ee ee ee ee en eo ee 
; 
; DEVICE HEADER 
; 
DRVDEV LABEL WORD 
DW -l1,-1 
DW BBO ;IBM format-compatible, Block 
DW STRATEGY 
DW DRVSIN 
DRVMAX DB 4 
DRVTBL LABEL WORD 
DW DRVSINIT 
DW MEDIASCHK 
DW GETSBPB 
DW CMDERR 
DW DRVSREAD 
DW EXIT 
DW EXIT 
DW EXIT 
DW DRVSWRIT 
DW DRVSWRIT 
DW EXIT 
DW EXIT 
DW EXIT 
H re Se eee) 
; 
; STRATEGY 
PTRSAV DD 4) 
‘STRATP PROC FAR 
STRATEGY: 
MOV WORD PTR [PTRSAV] ,BX 
MOV WORD PTR [PTRSAV+2],ES 
RET 
STRATP ENDP 
7 me ee ee we we ee es we ee we we we we we ee we we we ow we ee ee ee en i ee ee es 
; 
; MAIN ENTRY 
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CMDLEN = 4] ;LENGTH OF THIS COMMAND 
UNIT = 1 ;SUB UNIT SPECIFIER 
CMDC = 2 7;COMMAND CODE 
STATUS = 3 ; STATUS 
MEDIA = 13. —C *MEDIA DESCRIPTOR 
TRANS = 14 ; TRANSFER ADDRESS 
COUNT = 18 ;COUNT OF BLOCKS OR CHARACTERS 
START = 20 ;FIRST BLOCK TO TRANSFER 
DRVSIN: 
PUSH SI 
PUSH AX 
PUSH CX 
PUSH DX 
PUSH DI 
PUSH BP 
PUSH DS 
PUSH ES 
PUSH BX 
LDS BX, [PTRSAV] 7;GET POINTER TO I/O PACKET 
MOV AL,BYTE PTR [BX].UNIT 7AL = UNIT CODE 
MOV AH,BYTE PTR [BX].MEDIA ;AH = MEDIA DESCRIP 
MOV CX,WORD PTR [BX].COUNT ;CX = COUNT 
MOV DX,WORD PTR [BX].START ;DX = START SECTOR 
PUSH AX 
MOV AL,BYTE PTR [BX].CMDC 7;Command code 
CMP AL,11 
JA CMDERRP ;Bad command 
CBW 
SHL AX,1 72 times command = 
;word table index 
MOV SI,OFFSET DRVTBL 
ADD SI,AX ;Index into table 
POP AX ;Get back media 
sand unit 
LES DI,DWORD PTR [BX].TRANS ;ES:DI = TRANSFER 
; ADDRESS 
PUSH Cs 
POP DS 
ASSUME DS:CODE 
JMP WORD PTR [SI] 7GO DO COMMAND 
7 —— eee ee ee ee ee em wee ee ee ne ee re ee ee ee os ee oe es ee oe ee ee es oe ee os 
, 
; EXIT - ALL ROUTINES RETURN THROUGH THIS PATH 


’ 
ASSUME DS:NOTHING 
CMDERRP: 
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( } POP ~ AX ;Clean stack 
CMDERR: 
MOV AL,3 7 UNKNOWN COMMAND ERROR 
JMP SHORT ERRSEXIT 
ERRSCNT:LDS BX, [PTRSAV] 
SUB WORD PTR [BX] .COUNT,CX ;# OF SUCCESS. I/Os 
ERRSEXIT: 
;AL has error code 
MOV AH, 1@0@00@60901B ;MARK ERROR RETURN 
JMP SHORT ERR1 ; 
EXITP PROC FAR 
EXIT: MOV AH ,@8800901B 
ERR1: LDS BX, [PTRSAV] 
MOV WORD PTR [BX] .STATUS,AX 
;MARK OPERATION COMPLETE 
' POP BX 
POP ES 
POP DS 
POP BP 
POP DI 
( . a POP DX 
we. POP CX 
POP AX 
POP SI 
RET _ »RESTORE REGS AND RETURN 
EXITP ENDP 
CURDRV DB -1 
TRKTAB DB -1,-1,-1,-1 
SECCNT DW g 
DRVLIM = 8 ;Number of sectors on device 
SECLIM = 13 ;MAXIMUM SECTOR 
HDLIM = 15 ;MAXIMUM HEAD 


;WARNING - preserve order of drive and curhd! 


DRIVE DB 4] ; PHYSICAL DRIVE CODE 
CURHD DB G ;CURRENT HEAD 
CURSEC DB g ;CURRENT SECTOR 
CURTRK DW g ;CURRENT TRACK 
oo 4 ; 
4 MEDIASCHK: ;Always indicates Don't know 
ASSUME DS:CODE 
TEST AH, @G00G1G00B ;TEST IF MEDIA REMOVABLE 


JZ MEDIASEXT 
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XOR 
MEDIASEXT: 
LDS 
MOV 
JMP 


BUILDSBPB: 
ASSUME DS:CODE 
MOV 
CALL 
SETBPB: LDS 
MOV 
MOV 
MOV 
JMP 


BUILDBP: 


' DI,DI ;SAY I DON'T KNOW 


BX, [PTRSAV] 
WORD PTR [BX].TRANS,DI 


EXIT 
AH,BYTE PTR ES: [DI] *GET FAT ID BYTE 
GETBP ; TRANSLATE 


BX, [PTRSAV] 

[BX] .MEDIA,AH 
[BX] .COUNT,DI 
[BX] .COUNT+2,CS 
EXIT 


ASSUME DS:NOTHING 
7;AH is media byte on entry 
;DI points to correct BPB on return 


PUSH 
PUSH 


GOODID: 


HAS8: TEST 


HAS1: MOV 


AX 

CX 

DX 

BX 

CL,AH ;SAVE MEDIA 

CL,@F8H ; NORMALIZE 

CL, @F8H ;COMPARE WITH GOOD MEDIA BYTE 

GOODID 

AH, O@FEH ;DEFAULT TO 8-SECTOR, 
;SINGLE~SIDED 

AL,1l ;SET NUMBER OF FAT SECTORS 

BX,64*256+8 ;SET DIR ENTRIES AND SECTOR MAX 

CX,40*8 ;SET SIZE OF DRIVE 


DX,@1*256+1 ;SET HEAD LIMIT & SEC/ALL UNIT 
DI,OFFSET DRVBPB 
AH,@@8000190B ;TEST FOR 8 OR 9 SECTOR 


HAS8 7NZ = HAS 8 SECTORS 

AL 7 INC NUMBER OF FAT SECTORS 

BL 7 INC SECTOR MAX 

CX,49 ; INCREASE SIZE 

AH, ®@@8900G1B ;TEST FOR 1 OR 2 HEADS 
HAS1 724 = 1 HEAD 

CX,CX ;DOUBLE SIZE OF DISK 

BH,112 ; INCREASE # OF DIREC. ENTRIES 
DH ;INC SEC/ALL UNIT 

DL 7 INC HEAD LIMIT 


BYTE PTR [DI].2,DH 
BYTE PTR [DI].6,BH 
WORD PTR [DI].8,CX 
BYTE PTR [DI].10,AH 
BYTE PTR [DI].11,AL 
BYTE PTR [DI].13,BL 
BYTE PTR [DI].15,DL 
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a, POP " DX 
POP CX 
POP AX 
RET 


=e 


DISK I/O HANDLERS 


DRIVE NUMBER (0-3) 
MEDIA DESCRIPTOR 
SECTOR COUNT 
FIRST SECTOR 
= CS 
ES:DI = TRANSFER ADDRESS 
EXIT: 
IF SUCCESSFUL CARRY FLAG = @ 
ELSE CF=1 AND AL CONTAINS (MS-DOS) ERROR CODE, 
CX # sectors NOT transferred 


me ue TO TS TO TO TWO TH Te WH WS WH WE 
Has) 
twee ow 


DRVSREAD: 
ASSUME DS:CODE 
JICXZ DSKOK 


( ‘ CALL SETUP 
Jc DSKSIO 

CALL DISKRD 
JMP SHORT DSKSIO 

DRVSWRIT: 

ASSUME DS:CODE 
JICXZ DSKOK 
CALL SETUP 
JC DSKSIO 


CALL DISKWRT 
ASSUME DS:NOTHING 


DSKSIO: JNC DSKOK 
JMP ERRSCNT 

DSKOK: JMP EXIT 

SETUP: 

ASSUME DS:CODE 


;Input same as above 
7;On output 
= Trans addr 

DS:BX Points to BPB 

Carry set if error (AL is error code (MS-DOS) ) 


me Me MO TO Te NO NO NO NO 


ES:DI 


else 


[DRIVE] 
[SECCNT] 
[CURSEC] 
[CURHD] 


' [CURTRK] 


Drive number (8-3) 


Sectors to transfer 

Sector number of start of I/0 

Head number of start of I/O :Set 
Track # of start of I/O ;Seek performed 
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; All other registers destroyed 


INRANGE: 


XCHG 
CALL 
MOV 
ADD 
CMP 


JBE 
MOV 
STC 
RET 


MOV 
MOV 
XCHG 


BX,DI 7ES:BX = TRANSFER ADDRESS 
GETBP - sDS:DI = PTR TO B.P.B 
SI,CX 

SI,DX 


SI,WORD PTR [DI] .DRVLIM 

;COMPARE AGAINST DRIVE MAX 
INRANGE 
AL,8 


[DRIVE] ,AL 
[SECCNT] ,CX ;SAVE SECTOR COUNT 
AX ,DX ;SET UP LOGICAL SECTOR 

7;FOR DIVIDE 
DX ,DX 
WORD PTR [DI].SECLIM ;DIVIDE BY SEC PER TRACK 
DL 
[CURSEC] ,DL ;SAVE CURRENT SECTOR 
CX,WORD PTR [DI].HDLIM ;GET NUMBER OF HEADS 
DX,DX ;DIVIDE TRACKS BY HEADS PER CYLINDER 
CX 


[CURHD] ,DL 7;SAVE CURRENT HEAD 

{[CURTRK] , AX 7;SAVE CURRENT TRACK 

BX ;Xaddr 

DI ;BPB pointer 

CHKNEW ;Unload head if change drives 
DRIVESEL 

BL, [DRIVE] 

BH,BH ;BX drive index 

BX,OFFSET TRKTAB 7Get current track 
AX, [CURTRK] 

DL,AL ;Save desired track 

AL,DS: [BX] ;Make desired track current 
DISK+1,AL 7Tell Controller current track 
AL,DL ;At correct track? 

SEEKRET ;Done if yes 

BH,2 ;Seek retry count 

AL,-1 ;Position Known? 

NOHOME ;If not home head 

HOME 

SEEKERR 

AL,DL 

DISK+3,AL ;Desired track 

AL,1CH+STPSPD 3; Seek 

DCOM . 

AL,98H ;Accept not rdy, seek, & CRC errors 
SEEKRET 


SEEKERR ;No retries if not ready 
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DEC 'BH 
JINZ TRYSK 
SEEKERR:?: 
MOV BL, [DRIVE] 
XOR BH,BH ;BX drive index 
ADD BX,OFFSET TRKTAB ;Get current track 
MOV BYTE PTR DS: [BX] ,-l s;Make current track 
; lunknown 
CALL GETERRCD 
MOV CX, [SECCNT] ;Nothing transferred 
POP BX ;BPB pointer 
POP DI sXaddr 
RET 
SEEKRET: 
POP BX ;BPB pointer 
POP DI ;Xaddr 
CLC 
RET 
;? ee ce rw ree ee ee ae ee a cre re ee eae ee ee a DD DD OD Oe Ge a ew ae ee me 
; 
7 READ 
; 
DISKRD: 


ASSUME DS:CODE 
MOV CX, [SECCNT] 


RDLP: . 
CALL PRESET 
PUSH BX 
MOV BL,19 ;Retry count 
MOV DX ,DISK+3 ;Data port 
RDAGN: 
MOV AL, 8@H ;Read command 
CLI ;Disable for 1793 
ouT DISK,AL ;Output read command 
MOV BP,DI ;Save address for retry 
JMP SHORT RLOOPENTRY 
RLOOP: 
STOSB 
RLOOPENTRY: 
IN AL,DISK+5 ;Wait for DRQ or INTRQ 
SHR AL,1 
IN AL,DX ;Read data 
JNC RLOOP 
STI ;Ints OK now 
CALL GETSTAT 
AND AL,9CH 
. JZ RDPOP 30k 
MOV DI,BP ;Get back transfer 
DEC BL : 
JNZ RDAGN 
CMP AL,19H ;Record not found? 


INZ GOT_CODE ;No 
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MOV 
GOT CODE: 

~ CALL 

POP 

RET 


CE DRIVERS 


‘AL, 1 


GETERRCD 
BX 


BX 
RDLP 
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;Map it 


DISKWRT: 

ASSUME DS:CODE 
MOV 
MOV 
PUSH 
POP 

ASSUME DS:NOTH 

WRLP: 

CALL 

PUSH 
MOV 
MOV 


WRPOP: 


CX, [SECCNT] 


SI,DI 

ES 

DS 
ING 


PRESET 

BX 

BL,19 
DX,DISK+3 


AL, AGH 


DISK,AL 
BP,SI 


AL,DISK+5 
AL,1 


DX,AL 
WRLOOP 


SI 
GETSTAT 


WRAGN 
GETERRCD 
BX 


BX 


;Retry count 
;Data port 


;Write command 

;Disable for 1793 
Output write command 
;Save address for retry 


7Get data 
;Write data 


;Ints OK now 


;Ok 
;Get back transfer 
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;Select new head 
7;Go on to next track 
;Select head zero 


;First sector 
;Reset CURSEC 


sTell controller which sector 
;We go on to next sector 


;Step in w/ update, no verify 


;BX drive index 
3;Get current track 
;Next track 


;Restore with verify 


;No retries if not ready 
;Save real error code 
;Step in w/ update no verify 


;Get back real error code 


LOOP —° WRLP 
CLC 
RET 
PRESET: 
ASSUME DS:NOTHING 
MOV AL, [CURSEC] 
CMP AL,CS: [BX] .SECLIM 
JBE GOTSEC 
MOV DH, [CURHD] 
INC DH 
CMP DH,CS: [BX] .HDLIM 
JB SETHEAD 
- CALL STEP 
XOR DH,DH 
SETHEAD: 
MOV [CURHD] ,DH 
CALL DRIVESEL 
MOV AL,1l 
MOV {[CURSEC] , AL 
GOTSEC: 
OUT DISK+2,AL 
INC [CURSEC]} 
RET 
STEP: 
ASSUME DS:NOTHING 
MOV AL,58H+STPSPD 
CALL DCOM 
PUSH BX 
MOV BL, [DRIVE] 
XOR BH,BH 
ADD BX,OFFSET TRKTAB 
INC BYTE PTR CS: [BX] 
POP BX 
RET 
HOME: 
ASSUME DS:NOTHING 
MOV BL,3 
TRYHOM: 
MOV AL,@CH+STPSPD 
CALL DCOM 
AND AL,98H 
JZ RET3 
Js HOMERR 
PUSH AX 
MOV AL,58H+STPSPD 
CALL DCOM 
DEC BL 
POP AX 
JNZ TRYHOM 
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RET3: RET 


CHKNEW: 

ASSUME DS:NOTHING 
MOV AL, [DRIVE] ;Get disk drive number 
MOV AH,AL 
XCHG AL, [CURDRV] ;Make new drive current. 
CMP AL,AH ;Changing drives? 
JZ RET1 :No 


; If changing drives, unload head so the head load delay 
;One-sShot will fire again. Do it by seeking to the same 
;track with the H bit reset. 


v 


IN AL,DISK+tl ;Get current track number 
OUT DISK+3,AL ;Make it the track to seek 
MOV AL,1@H ;Seek and unload head 
DCOM : 
ASSUME DS:NOTHING 
OUT DISK,AL 
PUSH AX 
AAM ;Delay 18 microseconds 
POP AX 
GETSTAT: 
IN AL,DISK+4 
. TEST AL,DONEBIT 
JZ GETSTAT 
IN AL,DISK 


RET1: RET 


DRIVESEL: 

ASSUME DS:NOTHING 

;Select the drive based on current info 
;Only AL altered 


MOV AL, [DRIVE] 
OR AL,SMALBIT + DDBIT 35 1/4" IBM PC disks 
CMP [CURHD] ,@ 
JZ GOTHEAD 
OR AL,BACKBIT ;Select side 1 
GOTHEAD: 
OUT DISK+4,AL ;Select drive and side 
RET 
GETERRCD: 
ASSUME DS:NOTHING 
PUSH CX 
PUSH ES 
PUSH DI 
PUSH Cs 
POP ES ;Make ES the local segment 
MOV CS: [LSTERR],AL ;Terminate list w/ error code 
MOV CX ,NUMERR ;Number of error conditions 
MOV DI,OFFSET ERRIN ;Point to error conditions 


REPNE SCASB 
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( _ MOV ' AL,NUMERR-1[DI] ;Get translation 
: STc ;Flag error condition 
POP DI 
POP ES 
POP CX 
RET sand return 


gE RRR RR KEKE EKER ERE ERR ERE ERE ERERKRKREKREEREEEREKEKEEKREKK 
; BPB FOR AN IBM FLOPPY DISK, VARIOUS PARAMETERS ARE 
ae PATCHED BY GETBP TO REFLECT THE TYPE OF MEDIA 

; INSERTED 

: This is a nine sector single side BPB 

D 


RVBPB: 
DW 512 ;Physical sector size in bytes 
DB 1 *Sectors/allocation unit 
DW 1 sReserved sectors for DOS 
DB 2 7# of allocation tables 
DW 64 sNumber directory entries 
DW 9* 4G sNumber 512-byte sectors 
DB 11111160B s;Media descriptor 
DW 2 s;Number of FAT sectors 
DW 9 ;Sector limit 
DW 1 s;Head limit 
( INITAB DW DRVBPB ;Up to four units 
: DW DRVBPB 
DW DRVBPB 
DW DRVBPB 
ERRIN: ;DISK ERRORS RETURNED FROM THE 1793 CONTROLER 
DB 80H 7;NO RESPONSE 
DB 40H ;Write protect 
DB 20H ;Write Fault 
DB 1@H ;SEEK error 
DB 8 3;CRC error 
DB 1 ;Mapped from 10H 
; (record not found) on READ 
LSTERR DB 1) 7;ALL OTHER ERRORS 
ERROUT: ;RETURNED ERROR CODES CORRESPONDING TO ABOVE 
DB 2 ;NO RESPONSE 
DB i) ;WRITE ATTEMPT 
3;ON WRITE-PROTECT DISK 
DB SAH ;WRITE FAULT 
DB 6 ;SEEK FAILURE 
DB 4 ;BAD CRC 
DB 8 ; SECTOR NOT FOUND 
DB 12 ;GENERAL ERROR 
yj DRVSINIT: 


Determine number of physical drives by reading CONFIG.SYS 


™e Ne MO 
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ASSUME DS:CODE 


PUSH DS 
LDS SI, [PTRSAV] 
ASSUME DS:NOTHING 
LDS SI,DWORD PTR [SI.COUNT] ;DS:SI points to 
;CONFIG.SYS 
SCAN_LOOP: 
CALL SCAN SWITCH 
MOV AL,CL 
OR AL,AL 
JZ SCAN4 
CMP AL,"s" 
JZ SCAN4 
WERROR: POP DS 
ASSUME DS:CODE 
MOV DX,OFFSET ERRMSG2 
WERROR2: MOV AH,9 
INT 21H 
XOR AX,AX 
PUSH AX ;No units 
JMP SHORT ABORT 
BADNDRV: 
POP DS 
MOV DX,OFFSET ERRMSG1 
JMP WERROR2 
SCAN4: 
ASSUME DS:NOTHING 
7BX is number of floppies 
OR BX , BX 
JZ BADNDRV 7;User error 
CMP BX,4 
JA BADNDRV 7;USer error 
POP DS 
ASSUME DS:CODE 
PUSH -BX ;Save unit count 
ABORT: LDS BX, [PTRSAV] 
ASSUME DS:NOTHING 
POP AX 
MOV BYTE PTR [BX] .MEDIA,AL ;Unit count 
MOV [DRVMAX] , AL 
MOV WORD PTR [BX].TRANS,OFFSET DRVSINIT ;SET 
7;BREAK ADDRESS 
MOV [BX] .TRANS+2,CS ‘ 
MOV WORD PTR [BX] .COUNT,OFFSET INITAB 
7;SET POINTER TO BPB ARRAY 
MOV [BX] .COUNT+2,CS 
JMP EXIT 


; 
; PUT SWITCH IN CL, VALUE IN BX 
i 
SCAN_SWITCH: 

XOR BX, BX 
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(. & MOV — CX,BX 
: LODSB 
CMP AL,1@ 
JZ NUMRET 
CMP AL,"—" 
JZ - GOT SWITCH 
CMP AL,"/" 
JINZ SCAN SWITCH 
GOT SWITCH: 
CMP BYTE PTR [SI+1],":" 
JINZ TERROR 
LODSB 
OR AL,2@H ; CONVERT TO LOWER CASE 
MOV CL,AL 7; GET SWITCH 
LODSB 3; SKIP "3" 
v 
; GET NUMBER POINTED TO BY [SI] 
: 
; WIPES OUT AX,DX ONLY BX RETURNS NUMBER 
’ 
GETNUM1 : LODSB 
SUB AL,"@" 
JB CHKRET 
CMP AL,9 
JA CHKRET 
_ CBW 
( XCHG AX, BX 
MOV DX,19 
MUL DX 
ADD BX , AX 
JMP GETNUM1 
CHKRET: ADD AL,"@" 
CMP AL," " 
JBE NUOMRET 
CMP AL,"-" 
JZ NUMRET 
CMP AL,"/" 
JZ NUOMRET 
TERROR: 
POP DS ; GET RID OF RETURN ADDRESS 
JMP WERROR 
NUMRET: DEC SI 
RET 
ERRMSG1 DB "SMLDRV: Bad number of drives",13,19,"S" 
ERRMSG2 DB "SMLDRV: Invalid parameter",13,19,"S" 
CODE ENDS 
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2.8.2 Character Device Driver 


The following program illustrates a character device driver 
program. ; 


RRR AEKAEEEEKKEKKEEKERK DR CHARACTER DEVICE 444K REKKEAREKEKKEKE 


TITLE VT52 CONSOLE FOR 2.9 (IBM) 

Pee eee eee eee cee eee e esses ss sess sss sss ss sss tsetse sess: 

; 

; IBM ADDRESSES FOR 1/0 

; 

Pee eee eee es ese eee sess s sess sss sss sss ss sss sssssssssssse: 
CR=13 ;CARRIAGE RETURN 
BACKSP=8 ; BACKSPACE 
ESC=1BH 
BRKADR=6CH ;006C BREAK VECTOR ADDRESS 
ASNMAX=206 ;SIZE OF KEY ASSIGNMENT BUFFER 

CODE SEGMENT BYTE 


ASSUME CS:CODE,DS:NOTHING, ES: NOTHING 


=e 


C ON - CONSOLE DEVICE DRIVER 


° 
, 
° 
, 
e 
’ 

Cc 


ONDEV: ;HEADER FOR DEVICE "CON" 
DW -1,-1 
DW 1899900000010011B ;CON IN AND CON OUT 
DW STRATEGY 
DW ENTRY 
DB ‘CON : 
4 ——— ee me me ee ee ee om ee ee ee ee ee ee ee oe ee ee ee ee ee ee ee ee oe 
’ 
; COMMAND JUMP TABLES 
CONTBL: 
DW CONSINIT 
DW EXIT 
DW EXIT 
DW CMDERR 
DW CONS READ 
DW CONSRDND 
DW EXIT 
DW CONSFLSH 
DW CONSWRIT 
DW CONSWRIT 
DW EXIT 
DW EXIT 


CMDTABL DB ‘A’ 
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PTRSAV 


STRATP 


DW 
DB 


;cursor 


;cursor 


;cursor 


s;cursor 


;cursor 
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up 

down 
forward 
back 


position 


;erase display 


;erase line 


scursor 


position 


;Save cursor position 


;restore cursor position 


;reset mode 


;set mode 


Device entry point 


DD 


PROC 


STRATEGY: 


STRATP 


ENTRY: 


MOV 
MOV 
RET 


ENDP 


PUSH 
PUSH 
PUSH 
PUSH 


FAR 


;LENGTH OF THIS 


COMMAND 


7;SUB UNIT SPECIFIER 


;COMMAND CODE 
; STATUS 


*MEDIA DESCRIPTOR 
; TRANSFER ADDRESS 
;COUNT OF BLOCKS OR CHARACTERS 


;FIRST BLOCK TO 


WORD PTR CS: [PTRSAV] , BX 
WORD PTR CS: [PTRSAV+2],ES 


TRANSFER 
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PUSH ' DI 

PUSH BP 

PUSH DS 

PUSH ES 

PUSH BX 

LDS BX,CS:[PTRSAV] ;GET POINTER TO I/O PACKET 
MOV CX,WORD PTR DS:[{BX].COUNT 7;CX = COUNT 
MOV AL,BYTE PTR DS:[BX].CMD 

CBW 

MOV SI,OFFSET CONTBL 

ADD SI,AX 

ADD SI,AX 

CMP AL,11 

JA CMDERR 

LES DI,DWORD PTR DS: [BX].TRANS 

PUSH cs 

POP DS 


ASSUME DS:CODE 


JMP WORD PTR [SI] 7;GO DO COMMAND 
PAGE 
PSSST SSS HSS SS SSS SSS SSS SSS SSS SSS St Ss sss Sse sss esses 
72 
7= SUBROUTINES SHARED BY MULTIPLE DEVICES 
7= 
pT SP SSS SS SSS SSS HSS SSS SS SS SHS SSS See Sess ses esses sss 
7 LLL SS SS A Se ee Oe ee a ie ee ee em Oe emt oe em ees ee eee eS Ses ee aes 
; 
; EXIT - ALL ROUTINES RETURN THROUGH THIS PATH 
; 
BUSSEXIT: ;DEVICE BUSY EXIT 
MOV AH, 980080011B 
JMP SHORT ERR1 
CMDERR: 
MOV AL,3 ;UNKNOWN COMMAND ERROR 
ERRSEXIT: 
MOV AH, 10008901B ;MARK ERROR RETURN 
JMP SHORT ERR1 
EXITP PROC FAR 
EXIT: MOV AH ,8@8800001B 
ERR1: LDS BX,CS: [PTRSAV] 
MOV WORD PTR [BX].STATUS,AX ;MARK 


;OPERATION COMPLETE 
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( j POP ' BX 
, POP ES 
POP DS 
POP BP 
POP DI 
POP DX 
POP CX 
POP AX 
POP SI 
RET ;RESTORE REGS AND RETURN 


BREAK KEY HANDLING 


REAK: 
MOV CS:ALTAH,3 ; INDICATE BREAK KEY SET 
INTRET: IRET 
PAGE 
; 
; WARNING - Variables are very order dependent, 
so be careful when adding new ones! 
; 
WRAP DB g ; @ = WRAP, 1 = NO WRAP 
STATE DW Sl 
( MODE DB 3 
MAXCOL DB 79 
COL DB g 
ROW DB g 
SAVCR DW ] 
ALTAH DB g ;Special key handling 
? Se ee ee ee ee Cae ee te teh es GS Om Se AE ED SED SO UD ED END GSES Cine OH GD GUD GU AND WEED Mee em AD Me ND DD GD Om ee 
; 
; CHROUT - WRITE OUT CHAR IN AL USING CURRENT ATTRIBUTE 
; . 
ATTRW LABEL WORD 
ATTR DB 900001118 ;CHARACTER ATTRIBUTE 
BPAGE DB ] 7BASE PAGE 
base dw Gb88Gh 
chrout: cmp al,13 
jnz trylf 
mov [col] ,9@ 
jmp short setit 
trylf: cmp al,19 
jz lf 
cmp al,7 
jnz tryback 
torom: 
mov bx, [attrw] 
and b1,7 


mov ah,14 
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int 
ret5: ret 


tryback: 
cmp 
jnz 
cmp 
jz 
dec 
jmp 


outchrl1: 


lf: — inc 


scroll: call 
cmp 
jz 
cmp 
jz 
Mov 
jmp 

myscroll: 
mov 
mov 
mov 
mov 
mov 
mov 
xor 
mov 


19h 


al,8 

outchr 
[col] ,g 
ret5 

{col] 

short setit 


bx, [attrw] 
cx,l 

ah,9 

19h 

[col] 
al,[col] 
al, {maxcol] 
setit 
[wrap] ,@ 
outchrl 
[col] 


[col] ,@ 
[row] 
[row] ,24 
setit 
[row] ,23 
scroll 


dh,row 
dl,col 
bh,bh 
ah,2 
18h 


getmod 
al,2 
myscroll 
al,3 
myscroll 
al,1@ 
torom 


bh, [attr] 
bl,' ' 
bp,8@ 

ax, [base] 
es,ax 
ds,ax 
di,di 
si,169 
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sturn off video 


;turn on video 


sget column information 


;SAVE COUNT 
;GET CHAR IN AL 


;STORE CHAR AT ES:DI 


INTO AL 


mov ' ©X,23*8O 
cld 
cmp ax, @b80Gh 
jz colorcard 
rep movsw 
mov ax,bx 
mov cx,bp 
rep stosw 
sret: push cs 
pop ds 
ret 
colorcard: 
mov dx,3dah 
wait2: in al ,dx 
test al,8 
jz wait2 
mov al,25h 
mov dx ,3d8h 
out dx,al 
rep movsw 
mov ax,bx 
mov cx,bp 
rep stosw 
: mov al,29h 
mov dx,3d8h 
out dx,al 
jmp sret 
GETMOD: MOV AH,15 
INT 16 
MOV BPAGE,BH 
DEC AH 
MOV WORD PTR MODE,AX 
RET 
? ome re ee em ew oe ee ee ee ee ee ee ee ee oe eo 
a 
; CONSOLE READ ROUTINE 
, 
CONSREAD: 
JICXZ CONSEXIT 
CONSLOOP: 
PUSH CX 
CALL CHRIN 
POP CX 
STOSB 
LOOP CONSLOOP 
CONSEXIT: 
JMP EXIT 
? em eee ee ee we we ee oe oe ee ee we ee we we ee oe ee 
td 
; INPUT SINGLE CHAR 
’ 
CHRIN: XOR AX, AX 


MS-DOS 
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;Check for non-key after BREAK 


;Clear out holding buffer 


;Select segment @ 
;Reset KB queue head 


;Reset tail pointer 


XCHG AL,ALTAH 7;GET CHARACTER & ZERO ALTAH 
OR AL,AL 
JINZ KEYRET 
INAGN: XOR AH, AH 
INT 22 
ALT1@: 
OR AX, AX 
JZ INAGN 
OR AL, AL ;SPECIAL CASE? 
JINZ KEYRET 
MOV ALTAH,AH 7;STORE SPECIAL KEY 
KEYRET: RET 
7 LLL A a ee ee eee a cm ee ee ee oe 
, 
; KEYBOARD NON DESTRUCTIVE READ, NO WAIT 
’ 
CONSRDND: 
MOV AL, [ALTAH] 
OR AL,AL 
JINZ RDEXIT 
RD1: MOV AH,1 
INT 22 
JZ CONBUS 
OR AX, AX 
JINZ RDEXIT 
MOV AH,@ 
INT 22 
JMP CONSRDND 
RDEXIT: LDS BX, [PTRSAV] 
MOV [BX] .MEDIA,AL 
EXVEC: JMP EXIT 
CONBUS: JMP BUSSEXIT 
; LLL SS SS Se ee he me en Se Oe ee ee es ee ee 
a 
; KEYBOARD FLUSH ROUTINE 
a 
CONSFLSH: 
MOV [ALTAH] ,@ 
PUSH DS 
XOR BP,BP 
MOV DS,BP 
MOV DS:BYTE PTR 41AH,1EH 
;pointer 
MOV DS:BYTE PTR 41CH,1EH 
POP DS 
JMP EXVEC 


e 
c 
° 
e 
° 
td 
e 
, 

Cc 


CONSOLE WRITE ROUTINE 


ONSWRIT: 
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CONSLP: 


COUT: 


OUTC: 


IDEO: 


S1B: 
S1A3: 


ICXZ 
PUSH 


AH,3 . ;SET CURRENT CURSOR POSITION 


WORD PTR [COL] ,DX 
CX 


AL, ES: [DI] ;GET CHAR 


OUTC ;OUTPUT CHAR 
CONSLP ;REPEAT UNTIL ALL THROUGH 


OUTPUT SINGLE CHAR IN AL TO VIDEO DEVICE 


MOV 
JMP 


CMP 
JNZ 
MOV 
RET 


CALL 
MOV 
RET 


SI,OFFSET STATE 
[ST] 


AL, ESC ; ESCAPE SEQUENCE? 
S1B 
WORD PTR [SI] ,OFFSET S2 


CHROUT 
WORD PTR [STATE] ,OFFSET S1 
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$2: PUSH ° AX 


CALL GETMOD 
POP AX 
MOV BX,OFFSET CMDTABL-3 
S7A: ADD BX,3 
CMP BYTE PTR [BX] ,@ 
JZ S1A 
CMP - BYTE PTR [BX] ,AL 
JNZ S7A 
JMP WORD PTR [BX+1] 
MOVCUR: CMP BYTE PTR [BX] ,AH 
JZ SETCUR 
ADD BYTE PTR [BX],AL 
SETCUR: MOV DX,WORD PTR COL 
XOR BX,BX 
MOV AH,2 
INT 16 
JMP S1A 
CUP: MOV WORD PTR [SI],OFFSET CUP1 
RET 
CUPI1: SUB AL, 32 
" MOV BYTE PTR [ROW] ,AL 
MOV WORD PTR [SI] ,OFFSET CUP2 
RET 
CUP2: SUB AL,32 
MOV BYTE PTR [COL] ,AL 
JMP SETCUR 
SM: MOV WORD PTR [SI],OFFSET S1A 
RET 
CUH: MOV WORD PTR COL,@ 
JMP SETCUR 
CUF: MOV AH,MAXCOL 
MOV AL,1 
CUFI1: MOV BX,OFFSET COL 
JMP MOVCUR 
CUB: MOV AX, @OFFH 
JMP CUF1 
CUU: MOV AX, GGFFH 
CUU1L: MOV BX,OFFSET ROW 
JMP MOVCUR 
CUD: MOV AX,23*256+1 


JMP Ccuul 
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PSCP: MOV 
MOV 
JMP 


PRCP?: MOV 
MOV 
JMP 


ED: CMP 
JAE 


MOV 
MOV 
JMP 


ELL: MOV 
EL: MOV 
EL2: MOV 
ERASE: MOV 
MOV 
MOV 
INT 
ED3: JMP 


RM: MOV 
RET 
RM1: XOR 
MOV 

JMP 


CONSINIT: 
int 
and 
cmp 
jnz 
mov 

iscolor: 
cmp 
ja 
mov 
mov 


setbrks 
XOR 
MOV 
MOV 
MOV 
MOV 


MOV 
MOV 
MOV 


AX,WORD PTR COL 
SAVCR, AX 
SETCUR 


AX, SAVCR 
WORD PTR COL,AX 
SETCUR 


BYTE PTR [ROW] ,24 
ELL 


CX,WORD PTR COL 
DH,24 
ERASE 


BYTE PTR [COL] ,@ 
Cx,WORD PTR [COL] 
DH,CH 

DL,MAXCOL 


SETCUR 


WORD PTR [SI] ,OFFSET RM1 


CX,CX 
CH,24 
EL2 


1llh 
al,@G110900b 
al,@@110000b 
iscolor 
{base] ,@b¢@adh slook for bw card 
al,@8810000b 
setbrk 
{mode] ,@ 
{maxcol] ,39 


BX, BX 

DS,BX 

BX,BRKADR 

WORD PTR [BX] ,OFFSET BREAK 
WORD PTR [BX+2],CS 


BX,29H*4 
WORD PTR [BX] ,OFFSET COUT 
WORD PTR [BX+2],CS 
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slook for 49 col mode 
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LDS ' BX,CS: [PTRSAV] 
MOV WORD PTR [BX].TRANS,OFFSET CONSINIT 
;SET BREAK ADDRESS 
MOV [BX] .TRANS+2,CS 
JMP EXIT 
CODE ENDS 


END 


CHAPTER 3 


MS-DOS TECHNICAL INFORMATION 


3.1 MS-DOS INITIALIZATION 


MS-DOS initialization consists of several steps. Typically, 
a ROM (Read Only Memory) bootstrap obtains control, and then 
reads the boot sector off the disk. The boot sector then 
reads the following files: 


I0.SYS 
MSDOS.SYS 


Once these files are read, the boot process begins. 


3.2 THE COMMAND PROCESSOR 


The command processor supplied with |. MS-DOS (file 
COMMAND.COM.) consists of 3 parts: 


l. 


a 


A resident part resides in memory immediately 
following MSDOS.SYS and its data area. This part 
contains routines to process Interrupts 23H 
(CONTROL-C Exit Address) and 24H (Fatal Error Abort 
Address), as well as a routine to reload the 
transient part, if needed. All standard MS-DOS 
error handling is done within this part of 
COMMAND.COM. This includes displaying error 
messages and processing the Abort, Retry, or Ignore 
messages. 


An initialization part follows the resident part. 
During startup, the initialization part is given 
control; it contains the AUTOEXEC file processor 
setup routine. The initialization part determines 
the segment address at which programs can be 
loaded. It is overlaid by the first program 
COMMAND.COM loads because it is no longer needed. 
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3. 


A transient part is loaded at the high end of 
memory. This part contains all of the internal 
command processors and the batch file processor. 


The transient part of the command processor 
produces the system prompt (such as A>), reads the 
command from keyboard (or batch file) and causes it 
to be executed. For external commands, this part 
builds a command line and issues the EXEC system 
call (Function Request 4BH) to load and transfer 
control to the program. 
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3.3 MS-DOS DISK ALLOCATION 


The MS-DOS area is formatted as follows: 


Reserved area ~— variable size 


First copy of file allocation 
table - variable size 


Second copy of file allocation 
table - variable size 
(optional) 


Additional copies of file 
allocation table - variable 
size (optional) 


Root directory - variable size 
File data area 


Allocation of space for a file in the data area is not 
pre-allocated. The space is allocated one cluster at a 
time. A cluster consists of one or more consecutive 
sectors; all of the clusters for a file are "chained" 
together in the File Allocation Table (FAT). (Refer 
to Section 365, "File Allocation Table.") There is 
usually a second copy of the FAT kept, for consistency. 
Should the disk develop a bad sector in the middle of the 
first FAT, the second can be used. This avoids loss of data 
due to an unusable disk. 


3.4 MS-DOS DISK DIRECTORY 


FORMAT builds the root directory for all disks. Its 
location on disk and the maximum number of entries are 
dependent on the media. 


Since directories other than the root directory are regarded 


as files by MS-DOS, there is no limit to the number of files 
they may contain. 


All directory entries are 32 bytes in length, and are in the. 
following format (note that byte offsets are in 
hexadecimal): : 
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0-7 


Filename. Eight characters, left aligned and 
padded, if necessary, with blanks. The first 
byte of this field indicates the file status 
as follows: 


OGH The directory entry has never been 
used. This is used to limit the 
length of directory searches, for 
performance reasons. 


2EH The entry is for a directory. If 
the second byte is also 2EH, 
then the cluster field contains 
the cluster number of this 
directory's parent directory 
(@G@@GH if the parent directory 
is the root directory). Other- 
wise, bytes @1H through @AH 
are all spaces, and the cluster 
field contains the cluster 
number of this directory. 


E5H The file was used, but it has been 
erased. 


Any other character is the first character 
of a filename. 


Filename extension. 


File attribute. The attribute byte is 
mapped as follows (values are in hexa- 
decimal): 


G1 File is marked read-only. An attempt 
to open the file for writing using 
the Open File system call (Function 
Request 3DH) results in an error 
code being returned. This value 
can be used along with other 
values below. Attempts to delete 
the file with the Delete File 
system call (13H) or Delete a 
Directory Entry (41H) will also 
fail. 


G2 Hidden file. The file is excluded 
from normal directory searches. 


G4 System file. The file is excluded 
from normal directory searches. 


G8 The entry contains the volume label 
in the first 1l bytes. The entry 
contains no other usable information 


3-4: 
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( } : (except date and time of creation), 
and may exist only in the root 
directory. 


16 The entry defines a sub-directory, 
and is excluded from normal 
directory searches. 


20 Archive bit. The bit is set to "on" 
whenever the file has been written 
to and closed. 


Note: The system files (I0.SYS and 
MSDOS.SYS) are marked as read-only, 
hidden, and system files. Files can 
be marked hidden when they are created. 
Also, the read-only, hidden, system, 
and archive attributes may be changed 
through the Change Attributes system 
call (Function Request 43H). 


G@C-15 Reserved. 
16-17 Time the file was created or last updated. 
The hour, minutes, and seconds are mapped 
( ; into two bytes as follows: 


Offset 17H 
ae Nc ee a 
7 3 2 


Offset 16H 
|"|[M| mM] s|s|s|s]s| 
5 4 g 
where: 
H is the binary number of hours (9-23) 
M is the binary number of minutes 
(9-59) 
s is the binary number of two-second 
increments 


18-19 Date the file was created or last updated. 
The year, month, and day are mapped into two bytes 
as follows: 


Offset 19H 
}¥ |] ¥][Y JY [¥Y¥]¥]yv im] 
7 1 G 


Offset 18H 
|M|[M[M|[D|[D|[ DID IDI 
5 4 4) 
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where: 


Y is 8-119 (1980-2999) 
M is 1-12 
D is 1-31 


1A-1B Starting cluster; the cluster number 
of the first cluster in the file. 


Note that the first cluster for data space 
on all disks is cluster @@2. 


The cluster number is stored with the 
least significant byte first. 


NOTE 
Refer to Section 3.5.1, 
"How to Use the File 
Allocation Table," for details 
about converting cluster 
numbers to logical sector 


numbers. 


1C-1F File size in bytes. The first word of this 
four-byte field is the low-order part of 
the size. 
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3.5 FILE ALLOCATION TABLE (FAT) 


The following information is included for system programmers 
who wish to write installable device drivers. This section 
explains how MS-DOS uses the File Allocation Table to 
convert the clusters of a file to logical sector numbers. 
The driver is then responsible for locating the logical 
sector on disk. Programs must use the MS-DOS file 
management function calls for accessing files; programs 
that access the FAT are not guaranteed to be 
upwardly-compatible with future releases of MS-DOS. 


The File Allocation Table is an array of 12-bit entries (1.5 
bytes) for each cluster on the disk. The first two FAT 
entries map a portion of the directory; these FAT entries 
indicate the size and format of the disk. 


The second and third bytes currently always contain FFH. 


The third FAT entry, which starts at byte offset 4, begins 
the mapping of the data area (cluster 992). Files in the 
data area are not always written sequentially on the disk. 
The data area is allocated one cluster at a time, skipping 
over clusters already allocated. The first free cluster 
found will be the next cluster allocated, regardless of its 
physical location on the disk. This permits the most 
efficient utilization of disk space because clusters made 
available by erasing files can be allocated for new files. 


Each FAT entry contains three hexadecimal characters: 


GBB If the cluster is unused and available. 


FF7 The cluster has a bad sector in it. 
MS-DOS will not allocate such a cluster. 
CHKDSK counts the number of bad clusters 
for its report. These bad clusters are 
not part of any allocation chain. 


FF8-FFF Indicates the last cluster of a file. 


XXX Any other characters that are 
the cluster number of the next cluster in 
the file. The cluster number of the first 
cluster in the file is kept in the file's 
directory entry. 


The File Allocation Table always begins on the first section 
after the reserved sectors. If the FAT is larger than one 
sector, the sectors are continguous. Two copies of the FAT 
are usually written for data integrity. The FAT is read 
into one of the MS-DOS buffers whenever needed (open, read, 
write, etc.). For performance reasons, this buffer is given 
a high priority to keep it in memory as long as possible. 
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Seed. 


How To Use The File Allocation Table 


Use the directory entry to find the starting cluster of the 


file. 


l. 


Next, to locate each subsequent cluster of the file: 


Multiply the cluster number just used by 1.5 (each 
FAT entry is 1.5 bytes long). 


The whole part of the product is an offset into the 
FAT, pointing to the entry that maps the cluster 
just used. That entry contains the cluster number 
of the next cluster of the file. 


Use a MOV instruction to move the word at the 
calculated FAT offset into a register. 


If the last cluster used was an even number, keep 
the low-order 12 bits of the register by ANDing it 
with FFF; otherwise, keep the high-order 12 bits 
by shifting the register right 4 bits with a SHR 
instruction, 


If the resultant 12 bits are FFS8H-FFFH, the file 
contains no more clusters. Otherwise, the 12 bits 
contain the cluster number of the next cluster in 
the file. . 


To convert the cluster to a logical sector number (relative 


sector, 
DEBUG) : 


l. 


such as that used by Interrupts 25H and 26H and by 


Subtract 2 from the cluster number. 


Multiply the result by the number of sectors per 
cluster. 


Add to this result the logical sector number of the 
beginning of the data area. 


MS-DOS TECHNICAL INFORMATION Page 3-9 


3.6 MS-DOS STANDARD DISK FORMATS 


On an MS-DOS disk, the clusters are arranged on disk to 
minimize head movement for multi-sided media. All of the 
space on a track (or cylinder) is allocated before moving on 
to the next track. This is accomplished by using the 
sequential sectors on the lowest-numbered head, then all the 
sectors on the next head, and so on until all sectors on all 
heads of the track are used. The next sector to be used 
will be sector 1 on head @ of the next track. 


For disks, the following table can be nuseGe 


Sectors/ FAT size Dir Dir Sectors/ 
ae Track Sectors Sectors Entries Cluster 


Figure 4. 5-1/4" Disk Format 


The first byte of the FAT can sometimes be used to determine 
the format of the disk. The following 5-1/4" formats have 
been defined for the IBM Personal Computer, based on values 
of the first byte of the FAT. The formats in Table 3.1 are 
considered to be the standard disk formats for MS-DOS. 
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Table 3.1 MS-DOS Standard Disk Formats 


(5-1/4 5-1/4 5-1/4 5-1/4 8 8 8 

No. sides- 1 l 2 2 1 1 2 
Tracks/side 48 40 4g 4g 77 77 77 
Bytes/ 

sector 512 512 512 512 128 128 1024 
Sectors/ 

track 8 9 8 9 26 26 8 
Sectors/allo- 

cation unit 1 / ] 2 2 4 4 1 
Reserved 

sectors 1 1 l 1 1 4 1 
No. FATs 2 2 2 2 2 2 2 
Root directory 

entries 64 64 112 112 68 68 192 
No. sectors 326 360 640 7290 2082 2802 616 


Media Descriptor 
Byte FE FC FF FD FE* . ED FE* 


Sectors for 
1 FAT 1 2 1 20 6 6 2 


*The two media descriptor bytes that are the same for 
8" disks (FEH) is not a misprint. To establish 
whether a disk is single~ or double-density, a 
read of a single-density address mark should be 
made. If an error occurs, the media is double- 
density. 


CHAPTER 4 


MS-DOS CONTROL BLOCKS AND WORK AREAS 


4.1 TYPICAL MS-DOS MEMORY MAP 
O9BG38908 Interrupt vector table 
XXXX:3098G IO.SYS —- MS-DOS interface to hardware 


XXXX: 0000 MSDOS.SYS - MS-DOS interrupt handlers, 
service routines (Interrupt 21H functions) 


MS-DOS buffers, control areas, and installed 
device drivers 


XXXX: 0000 Resident part of COMMAND.COM - Interrupt 
handlers for Interrupts 22H (Terminate 
Address), 23H (CONTROL-C Exit Address), 
24H (Fatal Error Abort Address) 
and code to reload the transient part 


XXXX: 0000 External command or utility - (.COM or 
~-EXE file) 


XXXX: 0000 User stack for .COM files (256 bytes) 


XXXX: 0000 Transient part of COMMAND.COM - Command 
interpreter, internal commands, batch 
processor 


1. Memory map addresses are in segment:offset format. 
For example, @999:0000 is absolute address 99@@H. 


2. User memory is allocated from the lowest end of 
available memory that will meet the allocation 
request. 
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4.2 MS-DOS PROGRAM SEGMENT 


When an external command is typed, or when you execute a 
program through the EXEC system call, MS-DOS determines the 
lowest available free memory address to use as the start of 
the program. This area is called the Program Segment. 


The first 256 bytes of the Program Segment are set up by the 
EXEC system call for the program being loaded into memory. 
The program is then loaded following this block. An .EXE 
file with minalloc and maxalloc both set to zero is loaded 
as high as possible. 


At offset 9 within the Program Segment, MS-DOS builds the 
Program Segment Prefix control block. The program returns 
from EXEC by one of four methods: 


1. A long jump to offset @ in the Program Segment 
Prefix 


2. By issuing an INT 20H with CS:@ pointing at the PSP 


3. By issuing an INT 21H with register AH=@ with CS:9 
' pointing at the PSP, or 4CH and no restrictions on 
cs 


4. By a long call to location 5@H in the Program 
Segment Prefix with AH=@ or Function Request 4CH 


NOTE 


It is the responsibility of 
all programs to ensure that 
the CS register contains the 
segment address of the Program 


Segment Prefix when 
terminating via any of these 
methods, except Function 


Request 4CH. For this reason, 
using Function Request 4CH is 
the preferred method. 


All four methods result in transferring control to the 
program that issued the EXEC. During this -returning 
process, Interrupts 22H, 23H, and 24H (Terminate Address, 
CONTROL-C Exit Address, and Fatal Error Abort Address) 
addresses are restored from the values saved in the Program 
Segment Prefix of the terminating program. Control is then 
given to the terminate address. If this is a program 
returning to COMMAND.COM, control transfers to its resident 
portion. If a batch file was in process, it is continued; 
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otherwise, COMMAND.COM performs a checksum on the transient 
part, reloads it if necessary, then issues the system prompt 
and waits for you to type the next command. 


When a program receives control, the following conditions 
are in effect: 


For all programs: 


The segment address of the passed environment is 
contained at offset 2CH in the Program Segment 
Prefix. 


‘The environment is a series of ASCII strings 
(totaling less than 32K) in the form: 


NAME=parameter 


Each string is terminated by a byte of zeros, and 
the set of strings is terminated by another byte of 
zeros. The environment built by the command 
processor contains at least a COMSPEC= string (the 
parameters on COMSPEC define the path used by 

oe MS-DOS to locate COMMAND.COM on disk). The last 

( “ PATH and PROMPT commands issued will also be in the 

; environment, along with any environment strings 
defined with the MS-DOS SET command. 


The environment that is passed is a copy of the 
invoking process environment. If your application 
uses a "keep process" concept, you should be aware 
that the copy of the environment passed to you is 
static. That is, .it will not change even if 
subsequent SET, PATH, or PROMPT commands’ are 
issued, 


Offset 50H in the Program Segment Prefix contains 
code to call the MS-DOS function dispatcher. By 
placing the desired function request number in AH, 
a program can issue a far call to offset 59H to 
invoke an MS-DOS function, rather than issuing an 
Interrupt 21H. Since this is a call and not an 
interrupt, MS-DOS may place any code appropriate to 
making a system call at this position. This makes 
the process of calling the system portable. 


The Disk Transfer Address (DTA) is set to 8@H 
(default DTA in the Program Segment Prefix). 
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File control blocks at 5CH and 6CH are formatted 
from the first two parameters typed when the 
command was entered. If either parameter contained 
a pathname, then the corresponding FCB contains 
only the valid drive number. The filename field 
will not be valid. 


An unformatted parameter area at 81H contains all 
the characters typed after the command (including 
leading and imbedded delimiters), with the byte at 
89H set to the number of characters. If the <, >, 
or parameters were typed on the command line, they 
(and the filenames associated with them) will not 
appear in this area; redirection of standard input 
and output is transparent to applications. 


Offset 6 (one word) contains the number of bytes 
available in the segment. 


Register AX indicates whether or not the drive 
specifiers (entered with the first two parameters) 
are valid, as follows: 


AL=FF if the first parameter contained an 
invalid drive specifier (otherwise AL=@@) 


AH=FF if the second parameter contained an 
invalid drive specifier (otherwise AH=@9) 


Offset 2 (one word) contains the segment address of 
the first byte of unavailable memory. Programs 
must not modify addresses beyond this point unless 
they were obtained by allocating memory via the 
Allocate Memory system call (Function Request 48H). 
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For Executable’ (.EXE) programs: 


DS and ES registers are set to point to the Program 
Segment Prefix. 


CS,1IP,SS, and SP registers are set to the values 
passed by MS-LINK. 


For Executable (.COM) programs: 


All four segment registers contain the segment 
address of the initial allocation block that starts 
with the Program Segment Prefix control block. 


All of user memory is allocated to the program. If 
the program invokes another program through 
Function Request 4BH, it must first free some 
memory through the Set Block (4AH) function call, 
to provide space for the program being executed. 


The Instruction Pointer (IP) is set to 19@0H. 


The Stack Pointer register is set to the end of the 
program's segment. The segment size at offset 6 is 
( ‘ reduced by 10@H to allow for a stack of that size. 


A word of zeros is placed on top of the_ stack. 
This is to allow a user program to exit to 
COMMAND.COM by doing a RET instruction last. This 
assumes, however, that the user has maintained his 
stack and code segments. 
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Figure 5 illustrates the format of the Program Segment 
Prefix. All offsets are in hexadecimal. 
(offsets in hex) 

Long call to MS- 


INT 20H Reserved DOS function dis- 
patcher (5 bytes) ** 


Terminate address CTRL-C exit 
(IP, CS) address (IP) 


CTRL-C exit f/Hard error exit address 
address (CS) (IP, CS) 
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Used by MS-DOS *** 
2CH 


5CH 


Formatted Parameter Area 1 formatted as standard 
unopened FCB 6CH 


Formatted parameter Area 2 Formatted as standard 
unopened FCB (overlaid if FCB at 5CH is opened) 
88 


Unformatted Parameter Area 
(default Disk Transfer Area) 
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Figure 5. Program Segment Prefix 


IMPORTANT 


Programs must not alter any 
part of the Program Segment 
Prefix below offset 5CH. 


i) CHAPTER 5 


~-EXE FILE STRUCTURE AND LOADING 


NOTE 


This chapter describes .EXE 
file structure and loading 
procedures for systems that 
use a version of MS-DOS that 
is lower than 2.0. For MS-DOS 
2.8 and higher, use Function 
Request 4BH, Load and Execute 
a Program, to load (or load 
and execute) an .EXE file. 


The .EXE files produced by MS-LINK consist of two parts: 
Control and relocation information 
The load module 
( ) The .control and relocation information is at the beginning 
" of the file in an area called the header. The load module 
immediately follows the header. 


The header is formatted as follows. (Note that offsets are 
in hexadecimal.) 


Offset Contents 
08-81 Must contain 4DH, 5AH. 
92-83 Number of bytes contained in last page; 


this is useful in reading overlays. 


84-05 Size of the file in 512-byte pages, 
including the header. 


86-07 Number of relocation entries in table. 
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88-89 “Size of the header in 16-byte paragraphs. 
This is used to locate the beginning of 
the load module in the file. 


GA-G8B Minimum number of 16-byte paragraphs 
required above the end of the loaded 
program. 


@C-GD Maximum number of 16-byte paragraphs 
required above the end of the loaded 
program. If both minalloc and max- 
alloc are @, then the program will 
be loaded as high as possible. 


GE-OF Initial value to be loaded into stack 
segment before starting program exe- 
cution. This must be adjusted by 
relocation. 


10-11 =. Value to be loaded into the SP register 
before starting program execution. 

12-13 Negative sum of all the words in the 
file. 

14-15. Initial value to be loaded into the IP 


register before starting program 
execution. 


16-17 Initial value to be loaded into the CS 
register before starting program 
execution. This must be adjusted by 
relocation. 


18-19 Relative byte offset from beginning of 
run file to relocation table. 

1A-1B The number of the overlay as generated by 
MS-LINK. 


The relocation table follows the formatted area described 
above. This table consists of a variable number of 
relocation items. Each relocation item contains two fields: 
a two-byte offset value, followed by a two-byte segment 
value. These two fields contain the offset into the load 
module of a word which requires modification before the 
module is given control. The following steps describe this 
process: 


1. The formatted part of the header is read into. 
memory. Its size is 1BH. 
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2. 


A portion of memory is allocated depending on the 
size of the load module and the allocation numbers 
(@A-@B and @C-@D). MS-DOS attempts to allocate 
FFFFH paragraphs. This will always fail, returning 
the size of the largest free block. If this block 
is smaller than minalloc and loadsize, then there 
will be no memory error. If this block is larger 
than maxalloc and loadsize, MS-DOS will allocate 
(maxalloc + loadsize). Otherwise, MS-DOS will 
allocate the largest free block of memory. 


A Program Segment Prefix is built in the lowest 
part of the allocated memory. 


The load module size is calculated by subtracting 
the header size from the file size. Offsets 94-05 
and @8-89 can be used for this calculation. The 
actual size is downward-adjusted based on _ the 
contents of offsets 62-03. Based on the setting of 
the high/low loader switch, an appropriate segment 
is determined at which to load the load module. 
This segment is called the start segment. 


The load module is read into memory beginning with 
the start segment. 


The relocation table items are read into a work 
area. 


Each relocation table item segment value is added 
to the start segment value. This calculated 
segment, plus the relocation item offset value, 
points to a word in the load module to which is 
added the start segment value. The result is 
placed back into the word in the load module. 


Once all relocation items have been processed, the 
SS and SP registers are set from the values in the 
header. Then, the start segment value is added to 
SS. The ES and DS registers are set to the segment 
address of the Program Segment Prefix. The start 
segment value is added to the header CS register 
value. The result, along with the header IP value, 
is the initial CS:IP to transfer to before starting 
execution of the program. 
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